Connecting Claude.ai

Claude.ai connects to Bridge Town via OAuth — no API token needed. This is the recommended way to get started.

Bridge Town is bring-your-own-agent. Claude runs in your Claude.ai session; Bridge Town does not invoke server-side language models or proxy your prompts.

Prerequisites

A Claude.ai account (Pro, Team, or Enterprise)
A Bridge Town account

Connect

Open Claude.ai and sign in.
Click Customize.
Click + then Add custom connector.
Paste your Bridge Town MCP URL:
```
https://api.bridgetown.builders/mcp
```
Set Name to Bridge Town and paste the URL into Remote MCP server URL.
Click Connect.
Claude will redirect you to Bridge Town to authorise the connection. Sign in with your Bridge Town account and click Authorise.
You’re connected. Claude.ai can now access your Bridge Town workspace.

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

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

http://localhost:8000/mcp

Note: The local URL goes directly to the MCP server (port 8000). The cloud URL api.bridgetown.builders routes to the same service via Caddy.

Note: Claude.ai must be able to reach this URL. For local development, a tunnelling tool like ngrok or cloudflared is required.

Troubleshooting

“Connector not found”

Confirm you pasted the full URL including the /mcp path: https://api.bridgetown.builders/mcp
Note: The MCP endpoint is on api.bridgetown.builders, not app.bridgetown.builders

“Authorisation failed”

Make sure you’re signed in to Bridge Town before approving the connection
Try the flow again from the connectors page

“Tools not available”

Disconnect and reconnect the connector
Check that your Bridge Town account is active

“Too many tools / Claude can’t find the right tool”

Bridge Town exposes 75 tools total (plus 10 optional MCP Apps for interactive UI on supported hosts). Claude loads 14 hot-tier tools immediately and discovers the rest via Claude’s native tool search, search_tools, or get_tool.
If Claude seems unaware of a specific tool, ask: “Search Bridge Town tools for [what you want to do]” — this invokes search_tools to find the right tool.

“I expected an interactive widget but only see text”

Bridge Town uses stateful Streamable HTTP in production. Apps-capable sessions receive _meta.ui.resourceUri in tools/list, and the iframe runtime uses the GET /mcp SSE channel to finish its handshake. If you see text results but no widgets, the fallback text result is still complete; use the Troubleshooting Apps checks to confirm the session metadata and SSE channel are healthy.
Reconnecting the connector (remove, then re-add via Customize → + → Add custom connector) refreshes connector metadata and starts a fresh MCP session.

Skills and the `get_skill` compatibility bridge

Bridge Town ships 16 built-in skill templates — structured Jinja2 prompts that guide Claude through common FP&A workflows such as creating revenue models, formatting Google Sheets, or running scenario analysis. The canonical way to access skills is via MCP resources (skills:// for the catalog, skill://{name} for a specific template).

Claude.ai’s MCP connector does not autonomously read resources during a conversation, so Bridge Town provides get_skill — a compatibility bridge that lets Claude fetch any skill template through a standard tool call. It reads from the same canonical registry as the skill:// resources, so there is no separate or competing source of truth.

Recommended flow for Claude.ai users:

Ask Claude what you want to do (e.g. “Format a P&L Google Sheet with finance styles after writing the model output”).
Claude calls search_tools — the response now includes a skill_matches array alongside regular tool results. Each skill match includes a next_action hint such as get_skill(name='bridge-town-gsheet-formatting', include_template=true) and a related_tools list of the actual Bridge Town tools you need.
Claude calls get_skill with include_template=true to retrieve the full prompt template, then calls the related tools.

Example: formatting a P&L Google Sheet

“I’ve written P&L model output to a Google Sheet. Format it with finance-appropriate styles.”

Claude’s tool call sequence:

// Step 1 — discover the right skill
{"name": "search_tools", "arguments": {"query": "format P&L Google Sheet finance styles"}}

// search_tools response includes skill_matches:
{
  "items": [],
  "skill_matches": [
    {
      "name": "bridge-town-gsheet-formatting",
      "title": "Bridge Town Gsheet Formatting",
      "description": "Use whenever a Bridge Town agent is about to write model output to Google Sheets.",
      "resource_uri": "skill://bridge-town-gsheet-formatting",
      "related_tools": ["write_gsheet", "format_gsheet", "modify_gsheet_structure", "ingest_data_source"],
      "next_action": "get_skill(name='bridge-town-gsheet-formatting', include_template=true)"
    }
  ]
}

// Step 2 — fetch the full skill template
{"name": "get_skill", "arguments": {"name": "bridge-town-gsheet-formatting", "include_template": true}}

// Step 3 — apply the template: Claude reads the required context fields and calls
// the related tools returned above (write_gsheet, format_gsheet, etc.)
{"name": "format_gsheet", "arguments": {"project_name": "pl-model", "spec": {"kind": "preset", "preset": "financial_statement", ...}}}

get_skill is the recommended path for Claude.ai to consume skill templates. You can also use search_tools(domain="skills") — it returns skill_matches directly from the registry (not a resource redirect), making it a valid first step in the search_tools → get_skill workflow. The search_tools + get_skill workflow above is the correct end-to-end pattern for Claude.ai hosts.

See MCP Skills Resources for the full catalog of 16 bundled skills.

Resources and prompts

Claude.ai uses Bridge Town’s OAuth connector for the main modelling workflow. The Messages API MCP connector is tools-only, but full MCP clients can also surface Bridge Town resources and prompts. Use Claude Code, Claude Desktop, or a custom full MCP client if you need explicit resource attachment or slash-command style workflow prompts.

Errors from tools

Bridge Town tool errors include a hint field with a suggested next step. Claude will relay this hint automatically.
If you see “project-not-found”, verify the project name with list_projects.
Long-running model runs: use run with mode="async", then get_run to poll for completion. Claude handles this automatically for runs over 30 seconds.

Other clients

Codex, Gemini, OpenCode, ChatGPT-compatible runtimes, and custom MCP agents connect via API token instead of OAuth — see Connecting any MCP client.