Connecting any MCP Client

Bridge Town is built around the Model Context Protocol (MCP). Any MCP-compatible AI client — Claude, Codex, Mistral Vibe, Gemini, ChatGPT-compatible clients like OpenCode, custom in-house agents — can connect to your Bridge Town workspace using a standard MCP transport.

Bridge Town is bring-your-own-agent and bring-your-own-key. Your AI client and model provider run the model session; Bridge Town does not invoke server-side language models, broker hidden prompts, or process your conversation history.

If your client is Claude.ai, Claude Code, Claude Desktop, or the Claude API, the dedicated guides have copy-pasteable commands and config:

For everything else, follow the generic instructions below.

Connection profile

Bridge Town exposes one MCP endpoint, served as Streamable HTTP:

Field	Value
Transport	MCP Streamable HTTP
URL	`https://api.bridgetown.builders/mcp`
Auth (token)	`Authorization: Bearer btk_…`
Auth (OAuth)	Client metadata at `/.well-known/oauth-authorization-server` (Claude.ai uses this automatically)
Health endpoint	`GET /health` (HTTP, unauthenticated)

Bridge Town does not currently expose an SSE-only transport — clients that only speak the older transport=sse MCP transport will need an adapter such as mcp-remote.

Workspaces and workspace_id

How much of your Bridge Town account a connection can see depends on how it authenticates:

OAuth (Claude.ai, Mistral Vibe) resolves to your whole account. list_models returns models across every workspace you have an active membership in, each tagged with workspace_id/workspace_slug/ workspace_name. Pass that workspace_id into follow-up tool calls (read_file, run_model, commit_files, and most other model-scoped tools accept it) to operate on a workspace other than your default one.
Bearer tokens (Codex, Cursor, OpenCode, Claude Code, Claude Desktop, and every other client on this page) are scoped to the single workspace they were generated in. list_models returns only that workspace’s models, and passing a workspace_id for a different workspace is rejected with workspace-access-denied. To work in another workspace with a token-based client, generate a new token from that workspace at Connect AI and reconfigure the client with it.

1. Get an API token

Sign in to app.bridgetown.builders.
Open Connect AI at app.bridgetown.builders/connect.
Under Advanced → Claude Code (or Claude Desktop), click Generate token. The token is shown only once — copy it immediately.
Tokens always start with btk_. You can list and revoke them from the same page later.

Claude.ai users can skip this step and use OAuth — see Connecting Claude.ai.

2. Configure your MCP client

The exact configuration shape varies by client, but every MCP client needs three things: a transport (Streamable HTTP), a URL, and an Authorization header carrying your bearer token.

This client reference is generated from the same Connect AI catalog that renders the in-product setup cards.

Claude.ai (`claude-ai`)

Authentication: OAuth — no API token or install command.

Open Claude.ai connection settings, add Bridge Town’s remote MCP endpoint, and complete the OAuth consent flow:

https://api.bridgetown.builders/mcp

ChatGPT (`chatgpt`)

Authentication: OAuth — no API token or install command.

Open ChatGPT connection settings, add Bridge Town’s remote MCP endpoint, and complete the OAuth consent flow:

https://api.bridgetown.builders/mcp

Claude Code (`claude-code`)

Authentication: workspace-scoped Bridge Town API token.

Command:

claude mcp add --transport http bridge-town https://api.bridgetown.builders/mcp \
  --scope user \
  --header "Authorization: Bearer btk_YOUR_TOKEN"

Configuration location:

~/.claude.json

Scope: User scope — available from every working directory.

Verify:

claude mcp get bridge-town

Claude Desktop (`claude-desktop`)

Authentication: workspace-scoped Bridge Town API token.

Configuration:

{
  "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.

Codex (`codex`)

Authentication: workspace-scoped Bridge Town API token.

Command:

export BRIDGETOWN_TOKEN="btk_YOUR_TOKEN"
codex mcp add bridge-town \
  --url https://api.bridgetown.builders/mcp \
  --bearer-token-env-var BRIDGETOWN_TOKEN

Configuration:

[mcp_servers.bridge-town]
url = "https://api.bridgetown.builders/mcp"
bearer_token_env_var = "BRIDGETOWN_TOKEN"

Configuration location:

~/.codex/config.toml

Scope: User scope — available from every working directory.

Verify:

codex mcp get bridge-town

Cursor (`cursor`)

Authentication: workspace-scoped Bridge Town API token.

Configuration:

{
  "mcpServers": {
    "bridge-town": {
      "url": "https://api.bridgetown.builders/mcp",
      "headers": { "Authorization": "Bearer btk_YOUR_TOKEN" }
    }
  }
}

Configuration location:

~/.cursor/mcp.json

Scope: Global scope — available in every Cursor workspace.

Verify:

agent mcp list

GitHub Copilot (`copilot`)

Authentication: workspace-scoped Bridge Town API token.

Command:

code --add-mcp '{"name":"bridge-town","type":"http","url":"https://api.bridgetown.builders/mcp","headers":{"Authorization":"Bearer btk_YOUR_TOKEN"}}'

Configuration:

{
  "servers": {
    "bridge-town": {
      "type": "http",
      "url": "https://api.bridgetown.builders/mcp",
      "headers": { "Authorization": "Bearer ${input:bt_token}" }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "bt_token", "description": "Bridge Town API token", "password": true }
  ]
}

Configuration location:

Workspace: .vscode/mcp.json
User: profile mcp.json (open with MCP: Open User Configuration)

Scope: Workspace scope — this card uses .vscode/mcp.json.

Verify: Run MCP: List Servers and confirm bridge-town is running.

Gemini CLI (`gemini-cli`)

Authentication: workspace-scoped Bridge Town API token.

Command:

gemini mcp add bridge-town https://api.bridgetown.builders/mcp \
  --transport http \
  --scope user \
  --header "Authorization: Bearer btk_YOUR_TOKEN"

Configuration location:

~/.gemini/settings.json

Scope: User scope — available from every working directory.

Verify:

gemini mcp list

Windsurf (`windsurf`)

Authentication: workspace-scoped Bridge Town API token.

Configuration:

{
  "mcpServers": {
    "bridge-town": {
      "serverUrl": "https://api.bridgetown.builders/mcp",
      "headers": { "Authorization": "Bearer btk_YOUR_TOKEN" }
    }
  }
}

Configuration location:

macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

Scope: Global scope — Windsurf supports global MCP configuration only.

Verify: Open Cascade’s MCP Servers panel and confirm bridge-town is enabled.

Cascade caps all connected servers at a combined one-hundred-tool limit. If your combined tool count is near or above one hundred, disable other servers or unused tools.

Amp (`amp`)

Authentication: workspace-scoped Bridge Town API token.

Command:

amp mcp add bridge-town --header "Authorization=Bearer btk_YOUR_TOKEN" https://api.bridgetown.builders/mcp

Configuration location:

~/.config/amp/settings.json

Scope: Global scope — the command intentionally omits —workspace.

Verify:

amp mcp doctor

Mistral Vibe (`mistral-vibe`)

Authentication: OAuth — no API token or install command.

Open Mistral Vibe connection settings, add Bridge Town’s remote MCP endpoint, and complete the OAuth consent flow:

https://api.bridgetown.builders/mcp

OpenCode (`opencode`)

Authentication: workspace-scoped Bridge Town API token.

Command:

opencode mcp add bridge-town \
  --url https://api.bridgetown.builders/mcp \
  --header "Authorization=Bearer btk_YOUR_TOKEN"

Configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bridge-town": {
      "type": "remote",
      "url": "https://api.bridgetown.builders/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:BRIDGETOWN_TOKEN}" }
    }
  }
}

Configuration location:

~/.config/opencode/opencode.json

Scope: User scope — available from every working directory.

Verify:

opencode mcp list

Kimi Code (`kimi-code`)

Authentication: workspace-scoped Bridge Town API token.

Command:

export BRIDGETOWN_TOKEN="btk_YOUR_TOKEN"

Configuration:

{
  "mcpServers": {
    "bridge-town": {
      "url": "https://api.bridgetown.builders/mcp",
      "bearerTokenEnvVar": "BRIDGETOWN_TOKEN"
    }
  }
}

Configuration location:

~/.kimi-code/mcp.json

Scope: User scope — available from every working directory.

Verify: Open /mcp-config and confirm bridge-town is listed.

Z Code (`z-code`)

Authentication: workspace-scoped Bridge Town API token.

Setup:

Open Settings, then MCP Servers.
Choose New, select HTTP, and enter https://api.bridgetown.builders/mcp as the Service URL.
Add an Authorization header with the value Bearer btk_YOUR_TOKEN.

Configuration location:

User: ~/.zcode/cli/config.json
Workspace: <workspace-folder>/.zcode/config.json

Scope: User scope — choose User in the New MCP Server dialog.

Verify: Return to Settings → MCP Servers and confirm bridge-town is enabled.

Qwen Code (`qwen-code`)

Authentication: workspace-scoped Bridge Town API token.

Command:

qwen mcp add bridge-town https://api.bridgetown.builders/mcp \
  --transport http \
  --header "Authorization: Bearer btk_YOUR_TOKEN"

Configuration:

{
  "mcpServers": {
    "bridge-town": {
      "httpUrl": "https://api.bridgetown.builders/mcp",
      "headers": { "Authorization": "Bearer btk_YOUR_TOKEN" }
    }
  }
}

Configuration location:

~/.qwen/settings.json

Scope: User scope — this is Qwen’s default.

Verify:

qwen mcp list

Cline (`cline`)

Authentication: workspace-scoped Bridge Town API token.

Configuration:

{
  "mcpServers": {
    "bridge-town": {
      "type": "streamableHttp",
      "url": "https://api.bridgetown.builders/mcp",
      "headers": { "Authorization": "Bearer btk_YOUR_TOKEN" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Configuration location:

CLI: ~/.cline/mcp.json
macOS extension: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows extension: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux extension: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Scope: User scope — available from every working directory.

Verify: Open Cline → MCP Servers and confirm bridge-town is enabled without an error.

Goose (`goose`)

Authentication: workspace-scoped Bridge Town API token.

Configuration:

extensions:
  bridge_town:
    enabled: true
    type: streamable_http
    name: Bridge Town
    description: Bridge Town FP&A modelling tools
    uri: https://api.bridgetown.builders/mcp
    headers:
      Authorization: "Bearer btk_YOUR_TOKEN"
    timeout: 300

Configuration location:

macOS/Linux: ~/.config/goose/config.yaml
Windows: %APPDATA%\Block\goose\config\config.yaml

Scope: User scope — available in every Goose workspace.

Verify: Open Goose’s Extensions settings and confirm Bridge Town is enabled.

Aider (`aider`)

Authentication: workspace-scoped Bridge Town API token.

Unsupported: Aider does not currently support connecting to MCP servers.

Verify: Aider has no MCP connection to verify.

Droid (`droid`)

Authentication: workspace-scoped Bridge Town API token.

Command:

droid mcp add bridge-town https://api.bridgetown.builders/mcp \
  --type http \
  --header "Authorization: Bearer btk_YOUR_TOKEN" \
  --no-oauth

Configuration location:

~/.factory/mcp.json

Scope: User scope — Droid has no scope flag.

Verify:

droid mcp list

Anthropic Messages API connector

Anthropic’s Messages API MCP connector can call Bridge Town tools directly, but that API connector currently supports MCP tools only. Use the dedicated Claude API guide for the exact mcp_toolset.default_config.defer_loading=true configuration and the 14-tool hot list.

Use a full MCP client implementation instead when you need Bridge Town resources or prompts. Full clients can list/read product-reference resources such as templates:// and can surface Bridge Town workflow prompts. Behavioral skill packages are distributed separately; see Skills and connector packaging for the package boundary.

Custom or in-house agents

Any client that can speak MCP Streamable HTTP and attach an Authorization: Bearer … header is supported. We test against the mcp Python SDK and @modelcontextprotocol/sdk.

For custom discovery, load these 14 hot tools initially and defer the rest:

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

When the user asks for a workflow outside that set, call search_tools(query=...) and then get_tool(name=...) for the selected schema before invoking the cold tool.

3. Verify the connection

The simplest verification is to ask your agent to call any Bridge Town tool:

“Call list_models and tell me what you get back.”

If the agent gets a result back instead of an auth error, your connection is working.

You can also verify out-of-band with curl:

curl -fsS https://api.bridgetown.builders/health

The HTTP /health endpoint is unauthenticated and confirms the server is reachable. To check authentication, hit the MCP endpoint with your token:

curl -fsS -X POST https://api.bridgetown.builders/mcp \
  -H "Authorization: Bearer btk_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | head

A 200 OK with a tools array confirms both reachability and authorisation.

4. Manage tokens and rotation

Tokens are scoped to your user and tenant. To rotate or revoke:

Open app.bridgetown.builders/connect.
Find the token in the list and click Revoke.
Generate a new token and update your agent’s config.

Compromised tokens should be revoked immediately. Revoked tokens stop working for new requests within seconds. See Connect AI for the live token list.

Troubleshooting

“401 Unauthorized”

The token is missing, mistyped, or revoked. Re-create it from Connect AI.
Confirm the header is exactly Authorization: Bearer btk_… (not Token …).

“Tools not showing up”

Restart the client after editing config.
Confirm the URL ends with /mcp (not just the host).
Call tools/list directly (see the curl example above) — if it returns a tools array, the connection is working and the issue is client-side tool surfacing.

“Server disconnected” / “Stream closed”

Streamable HTTP keeps a persistent connection. Some corporate proxies break it — try a direct network or a tunnel (e.g. cloudflared).

“Transport not supported”

Your client may not support Streamable HTTP transport. Use the mcp-remote bridge JSON config above.

Connect AI — manage API tokens
Connecting Claude.ai — OAuth flow, no token
Connecting Claude Code — CLI shortcut
Connecting the Claude API — Messages API MCP connector
Connecting Claude Desktop — Desktop config
Skills and connector packaging — separately distributed behavioral packages

Connecting any MCP Client

Connection profile

Workspaces and workspace_id

1. Get an API token

2. Configure your MCP client

Claude.ai (claude-ai)

ChatGPT (chatgpt)

Claude Code (claude-code)

Claude Desktop (claude-desktop)

Codex (codex)

Cursor (cursor)

GitHub Copilot (copilot)

Gemini CLI (gemini-cli)

Windsurf (windsurf)

Amp (amp)

Mistral Vibe (mistral-vibe)

OpenCode (opencode)

Kimi Code (kimi-code)

Z Code (z-code)

Qwen Code (qwen-code)

Cline (cline)

Goose (goose)

Aider (aider)

Droid (droid)

Anthropic Messages API connector

Custom or in-house agents

3. Verify the connection

4. Manage tokens and rotation

Troubleshooting

Related

Claude.ai (`claude-ai`)

ChatGPT (`chatgpt`)

Claude Code (`claude-code`)

Claude Desktop (`claude-desktop`)

Codex (`codex`)

Cursor (`cursor`)

GitHub Copilot (`copilot`)

Gemini CLI (`gemini-cli`)

Windsurf (`windsurf`)

Amp (`amp`)

Mistral Vibe (`mistral-vibe`)

OpenCode (`opencode`)

Kimi Code (`kimi-code`)

Z Code (`z-code`)

Qwen Code (`qwen-code`)

Cline (`cline`)

Goose (`goose`)

Aider (`aider`)

Droid (`droid`)