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. Anthropic processes the conversation under your agreement with Anthropic; Bridge Town receives the MCP tool calls Claude Desktop sends.

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):

{
  "mcpServers": {
    "bridge-town": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://api.bridgetown.builders/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer btk_YOUR_TOKEN" }
    }
  }
}

Configuration location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Scope: User scope — applies to this Claude Desktop profile.

Verify: Restart Claude Desktop, then confirm bridge-town in Connectors.

3. Save and restart Claude Desktop.

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

Tool loading

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

search_tools, get_tool, list_models, create_model, list_files, read_file,
describe_model, commit_files, patch_file, run_model, 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

Claude Desktop is a full MCP client path when paired with mcp-remote. Bridge Town product-reference resources such as templates:// and the Native Sheets schema 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

Ask Claude:

“Check if Bridge Town is connected”

Claude will call the list_models tool and confirm the connection succeeded.

MCP Apps host status

Claude Desktop chat and Cowork are separate host surfaces. A result observed in one does not prove interactive rendering in the other.

This status is generated from docs-site/src/data/mcp-apps-host-support.json; do not infer one Claude surface’s behavior from another.

Evidence baseline (2026-09-03): deployed source 8cb696f0a81fb4afe7c7068434e88b67acc519d0; catalog 21e339c9414143a70c061b13c43e8c44c0c7abf93b60ac1ff1fd740e3b76923d; Claude profile dddf08f3b9afa4f8b6d12580ad86886c4266f1e610277950d8818940515a93d9. The exact-release live-host gate is pending and remains owned by the release operator.

Surface	Production evidence	Interactive Apps status	Recovery limit
Claude Desktop chat	No release-bound live Claude Desktop chat session is retained. Release 8cb696f0a81fb4afe7c7068434e88b67acc519d0 proves only the shared deployed server and source contract for canonical App bindings, resources, structured output, and text fallback—not Desktop end-to-end behavior.	Desktop tool/fallback behavior and interactive rendering are unverified for this release and must not be inferred from Claude.ai, Cowork, the shared server contract, or a simulator.	Restarting Desktop or reloading its MCP configuration only starts a new client session; it does not guarantee App support or rendering. Check the Desktop version, initialize capability, mapped tool binding, and matching resources/read before classifying the failure.
Cowork	On deployed release 4750db4763b3effde73e9864cc6f56e61ada217d, Cowork identified through claude-code 2.1.252, omitted the UI extension, invoked get_native_sheet, and did not read ui://apps/native-sheet-editor. Static binding fix 5b9f2a45a517752d6cd299d9199b758a9b231421 was deployed in 8cb696f0a81fb4afe7c7068434e88b67acc519d0, but no later visible-render receipt exists.	Tool execution and fallback are production-proven. Interactive rendering is not production-proven after the binding fix; a raw JSON or text result is a host-path observation, not proof of a stale connector.	Reconnecting cannot make an incapable Cowork transport render Apps. Retain the client family/version and the mapped-tool/no-resource-read sequence, continue with the complete fallback, and wait for release-bound operator acceptance before claiming interactive support.

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.