Skip to content

Connecting Claude Code

Claude Code connects to Bridge Town via the Model Context Protocol (MCP) over Streamable HTTP.

Bridge Town is bring-your-own-agent. Claude Code runs locally in your development environment and calls Bridge Town’s MCP tools with the access you grant. Bridge Town does not invoke server-side language models.

Prerequisites

Section titled “Prerequisites”

Connect

Section titled “Connect”

Run this command in your terminal (replace btk_YOUR_TOKEN with your actual token):

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

Restart Claude Code after adding the server.

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

Tool search profile

Section titled “Tool search profile”

Claude Code performs MCP tool search for large toolsets. Bridge Town’s runtime marks 14 hot tools as always loaded and the remaining tools as deferred in MCP metadata; Claude Code can also search by tool name and description.

For explicit testing of the final 1.0 hot/cold profile, launch Claude Code with:

Terminal window
ENABLE_TOOL_SEARCH=auto:5 claude

Use the default behaviour for normal work. The auto:5 setting is useful when you want Claude Code to search the catalog and inspect up to five candidate tools before calling a cold tool.

Resources and prompts

Section titled “Resources and prompts”

Claude Code is a full MCP client. Bridge Town resources can be referenced as MCP resources when your Claude Code version exposes them, and Bridge Town workflow prompts are available through the MCP prompt/slash-command path. The Anthropic Messages API MCP connector does not expose those primitives automatically; it supports MCP tools only.

Verify

Section titled “Verify”

Ask Claude:

“Check if Bridge Town is connected”

Claude will read the health://status resource and show your tenant ID and user ID if everything is working.

Self-hosted / local dev

Section titled “Self-hosted / local dev”

If you’re running Bridge Town locally via Docker Compose:

Terminal window
claude mcp add bridge-town http://localhost:8000/mcp --transport http \
  --header "Authorization: Bearer btk_YOUR_TOKEN"

Troubleshooting

Section titled “Troubleshooting”

“Connection refused”

  • Check the MCP server is running: curl http://localhost:8000/health
  • Verify the URL matches your deployment

“401 Unauthorized”

  • Verify your token is correct and not revoked
  • Token must start with btk_

“Tools not showing up”

  • Restart Claude Code after adding the MCP server
  • Check claude mcp list to verify the server was added

Other clients

Section titled “Other clients”

Codex, Gemini, OpenCode, ChatGPT-compatible runtimes, and custom MCP agents follow the same Streamable HTTP + bearer token pattern — see Connecting any MCP client for the generic config.