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 every Bridge Town workspace your account belongs to — not just one.

Verify

Ask Claude:

“Check if Bridge Town is connected”

Claude will call the list_models tool and confirm the connection is working.

Working across workspaces

Because Claude.ai connects via OAuth, it can see and act on every workspace your account has an active membership in — for example a personal workspace and a team workspace — without reconnecting. list_models returns one row per model across all of them, each tagged with its workspace_id, workspace_slug, and workspace_name. If the same model name exists in more than one workspace, use workspace_id (not the name) to tell them apart.

Ask Claude naturally and it will carry the right workspace forward:

“What models do I have access to?” → Claude calls list_models and lists models grouped by workspace.

“Open the budget-fy27 model in the Bridge Town workspace, not my personal one.” → Claude passes that model’s workspace_id into read_file, run, and any other follow-up tool calls.

This is OAuth-only. API tokens (used by Codex, Mistral Vibe, and other token-based clients — see Other clients below) stay scoped to the single workspace the token was generated in and cannot cross into another workspace.

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 82 tools total (plus 8 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”

This is almost always a per-session or per-connector state issue, not a Bridge Town outage — production runs a scheduled canary that proves the Apps handshake independently of any single session. The fallback text result is always complete; nothing is broken while you fix this.
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, use the Troubleshooting Apps checks to confirm the session metadata and SSE channel are healthy.
Start a new conversation, or reconnect the connector (remove, then re-add via Customize → + → Add custom connector) — both force a fresh initialize handshake and refresh connector metadata.

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": {"model_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 model name with list_models.
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, Mistral Vibe, Gemini, OpenCode, ChatGPT-compatible runtimes, and custom MCP agents connect via API token instead of OAuth. Token connections stay scoped to the single workspace the token was issued in — see Connecting any MCP client.