Skip to content

Connecting Claude Desktop

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

Bridge Town is bring-your-own-agent. Claude Desktop runs the model session; Bridge Town does not invoke server-side language models or proxy your prompts.

Prerequisites

Section titled “Prerequisites”

Connect

Section titled “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://api.bridgetown.builders/mcp",
      "--header",
      "Authorization: Bearer btk_YOUR_TOKEN"
    ]
  }
}
  1. Save and restart Claude Desktop.

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

Tool loading

Section titled “Tool loading”

Bridge Town exposes 75 MCP tools. The final hot tier keeps these 14 tools non-deferred for first-turn modelling work:

search_tools, get_tool, list_projects, create_project, list_files, read_file,
describe_model, commit_files, patch_file, run, get_run, list_runs,
list_data_sources, query_data

The remaining tools stay available through MCP tool search or Bridge Town’s search_tools and get_tool discovery fallback.

Resources and prompts

Section titled “Resources and prompts”

Claude Desktop is a full MCP client path when paired with mcp-remote. Bridge Town resources such as health://status, scaffold://default, skills://, and templates:// can be surfaced by clients that support MCP resources. Bridge Town workflow prompts are available to clients that support MCP prompts. The Anthropic Messages API MCP connector is different: it supports MCP tools only, so resources and prompts require this full-client style integration.

Verify

Section titled “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

Section titled “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

Section titled “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

Section titled “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.