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. Your configured model provider processes the conversation under your agreement with that provider. Bridge Town does not invoke server-side language models; it receives the MCP tool calls Claude Code sends.

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 --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 with claude mcp get bridge-town.

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 call the list_models tool and confirm the connection is working.

Troubleshooting

Section titled “Troubleshooting”

“Connection refused”

  • 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.