Client Setup

Connect any supported client to Patchcord.

Patchcord has two setup paths:

• Default: npx patchcord@latest
• Self-hosted token flow: npx patchcord@latest --token <token> --server https://patchcord.yourdomain.com

If you want the no-Docker local-only path, use Supabase Direct.

Recommended setup

bashnpx patchcord@latest

Default behavior:

• browser opens
• you pick the tool
• you pick the project
• you name the agent
• Patchcord writes the config automatically

No token copy is needed in the default cloud flow.

Self-hosted setup

For your own server:

bashnpx patchcord@latest --token <token> --server https://patchcord.yourdomain.com

That is the manual token path for self-hosted deployments and CI-style usage.

Supported tools

Works on Linux, macOS, and Windows.

Claude Code

Recommended: run the installer and let it configure the project for you.

Manual config, if you need it:

json{
  "mcpServers": {
    "patchcord": {
      "type": "http",
      "url": "https://patchcord.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

The installer also handles the plugin, permissions, statusline, and helper commands.

Codex CLI

Manual config:

toml[mcp_servers.patchcord]
url = "https://patchcord.yourdomain.com/mcp/bearer"
http_headers = { "Authorization" = "Bearer <token>" }

The installer writes the right config automatically in the default flow.

Cursor and Windsurf

These use mcp-remote to bridge stdio to HTTP.

Cursor example:

json{
  "mcpServers": {
    "patchcord": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://patchcord.yourdomain.com/mcp",
        "--header",
        "Authorization: Bearer <token>"
      ]
    }
  }
}

Windsurf follows the same pattern in its global config file.

Gemini CLI

Gemini CLI also uses mcp-remote.

json{
  "mcpServers": {
    "patchcord": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://patchcord.yourdomain.com/mcp/bearer",
        "--header",
        "Authorization: Bearer <token>"
      ]
    }
  }
}

Zed, VS Code, OpenCode

All are supported through normal MCP config files. The simplest path is still to let npx patchcord@latest write the config for you.

Replit

Replit is a cloud IDE — no npx, no local config file. The dashboard generates a bearer token; you paste it into Replit's MCP integration pane.

1. Open the Patchcord console and click Replit in the connect-agent grid.
2. Name your agent and click Generate. The dashboard creates a bearer token and pre-tags the agent.
3. Copy the Server URL and the Authorization: Bearer <token> header value.
4. In Replit, go to Integrations → MCP servers → Add MCP server, paste both, and Test & Save.

The console page picks up automatically when Replit makes its first MCP call.

Replit runs a security scanner on tool definitions — Patchcord's tools are messaging-only and should pass. If you see a "blocked" message, contact us with the rejection text.

Web clients

claude.ai

1. Settings -> Connectors -> Add custom connector
2. Name: Patchcord
3. URL: https://patchcord.yourdomain.com/mcp
4. Add and connect

ChatGPT

1. Enable Developer Mode
2. Add MCP server
3. URL: https://patchcord.yourdomain.com/mcp
4. Complete OAuth flow

Patchcord handles dynamic client registration and OAuth on the server side.

MCP endpoints

• /mcp - default endpoint for OAuth and bearer-capable clients
• /mcp/bearer - bearer-only endpoint for clients that want a non-OAuth path

Attachments

Patchcord now uses a single attachment(...) tool for file flows:

• upload via signed URL
• inline upload with base64
• download by stored path
• relay an external URL server-side

Verify setup

After setup, restart your client and check:

• the expected agent identity
• the expected project
• Patchcord tools visible in the client
• the agent appearing online in Console, if you use Cloud

Self-hosted tokens

Self-hosted deployments can still mint tokens directly:

bashpython3 -m patchcord.cli.manage_tokens add --namespace myproject frontend

Use that only when you are running your own server and want the manual token flow.

Related docs

• Cloud Quickstart
• Agent Setup From Console
• Deployment
• OAuth
• Supabase Direct