Connecting any MCP Client

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

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

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 (cloud)	`https://app.bridgetown.builders/mcp`
URL (local)	`http://localhost:8000/mcp`
Auth (token)	`Authorization: Bearer btk_…`
Auth (OAuth)	Client metadata at `/.well-known/oauth-authorization-server` (Claude.ai uses this automatically)
Health resource	`health://status` (MCP resource)
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.

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.

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://app.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://app.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://app.bridgetown.builders/mcp \
  --transport http \
  --header "Authorization: Bearer btk_YOUR_TOKEN"

Codex / OpenAI-compatible agents

Bridge Town does not require any OpenAI-specific glue — Codex and other ChatGPT/OpenAI-compatible runtimes 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.

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-… (rather than Claude), Bridge Town treats the connection identically — the MCP tool surface is model-agnostic.

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.

3. Verify the connection

Every Bridge Town MCP server exposes a health://status MCP resource that returns the authenticated tenant ID, user ID, and server build. The simplest verification is to ask your agent:

“Read the health://status resource and tell me my tenant ID.”

If the agent returns a tenant_id and user_id, your connection is working.

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

curl -fsS https://app.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://app.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).
Check health://status directly — if you get a tenant ID, 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).
For local development, ensure the server is running: curl http://localhost:8000/health.

“Transport not supported”

Your client may only support the legacy SSE 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 Claude Desktop — Desktop config
Self-Hosting with Docker Compose — local MCP endpoint