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:

• Connecting Claude.ai
• Connecting Claude Code
• Connecting the Claude API
• Connecting Claude Desktop

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, 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

1. Sign in to app.bridgetown.builders.
2. Open Connect AI at app.bridgetown.builders/connect.
3. Under Advanced → Claude Code (or Claude Desktop), click Generate token. The token is shown only once — copy it immediately.
4. 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.

Generic JSON config

Most desktop clients (Claude Desktop, OpenCode, Cursor, Continue, custom hosts) read an mcpServers block in JSON. The canonical shape is:

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

If the client only understands the older spawn-based shape (no native HTTP transport), bridge through mcp-remote:

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

CLI config

Clients with a CLI (such as Claude Code) usually accept the URL and headers as flags. The pattern is:

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

Codex, Mistral Vibe, and other OpenAI/tool-calling-compatible agents

Bridge Town does not require any provider-specific glue — Codex, Mistral Vibe, and other ChatGPT/OpenAI-compatible or tool-calling runtimes all connect through the same MCP Streamable HTTP endpoint with a bearer token. Configure your agent host’s mcpServers block using either of the JSON snippets above.

Mistral Vibe users can also connect via OAuth from chat.mistral.ai instead of generating a token — Bridge Town’s /mcp endpoint allows the https://chat.mistral.ai browser origin for the OAuth preflight, same as Claude.ai.

If you are using OpenCode, paste the JSON config block above into your opencode.json (or equivalent) and restart the agent.

If your runtime exposes a model like gpt-… or a Mistral model (rather than Claude), Bridge Town treats the connection identically — the MCP tool surface is model-agnostic.

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 resources such as skills:// and templates://, and can surface Bridge Town workflow prompts. See MCP Skills Resources for the full catalog of bundled skill templates available via skills://.

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

1. Open app.bridgetown.builders/connect.
2. Find the token in the list and click Revoke.
3. 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 only support the legacy SSE transport. Use the mcp-remote bridge JSON config above.

Related

• 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
• MCP Skills Resources — canonical bundled skill catalog (skills://)