Connecting Claude Desktop

Claude Desktop connects to Bridge Town via the Model Context Protocol using mcp-remote as a transport bridge.

Prerequisites

• Claude Desktop installed
• Node.js 18+ (for npx mcp-remote)
• A Bridge Town account with an API token (create one from Connect AI or directly at app.bridgetown.builders/connect)

Connect

1. Open Claude Desktop → Settings → Developer → Edit Config

2. Add this inside the "mcpServers" object (replace btk_YOUR_TOKEN):

{
  "bridge-town": {
    "command": "npx",
    "args": [
      "-y", "mcp-remote",
      "https://app.bridgetown.builders/mcp",
      "--header",
      "Authorization: Bearer btk_YOUR_TOKEN"
    ]
  }
}

3. Save and restart Claude Desktop.

In Bridge Town, you can manage and revoke tokens from Connect AI (/connect).

Verify

Ask Claude:

“Check if Bridge Town is connected”

Claude will read the health://status resource and return your tenant and user IDs.

Self-hosted / local dev

For a local Docker Compose deployment, change the URL:

{
  "bridge-town": {
    "command": "npx",
    "args": [
      "-y", "mcp-remote",
      "http://localhost:8000/mcp",
      "--header",
      "Authorization: Bearer btk_YOUR_TOKEN"
    ]
  }
}

Troubleshooting

“Server disconnected”

• Check the MCP server is reachable from your machine
• mcp-remote needs Node.js 18+ — run node --version to check

“401 Unauthorized”

• Verify your token starts with btk_ and is not revoked
• Tokens are shown only once at creation — create a new one if lost

Tools panel empty

• Restart Claude Desktop fully (quit and reopen)
• Check the Developer console for connection errors

Other clients

The same mcp-remote JSON shape works for any desktop MCP host whose config follows the mcpServers convention — Codex, OpenCode, Cursor, Continue, and others. See Connecting any MCP client for the generic walkthrough.