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; Anthropic processes the conversation under your agreement with Anthropic. Bridge Town does not invoke server-side language models or proxy your prompts; it receives the MCP tool calls Claude sends.

Prerequisites

A Claude.ai account whose workspace policy allows custom connectors
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.

Review the initial permissions

The first connection requests all nine approved Bridge Town capability scopes: models:read, models:write, runs:execute, history:read, data:read, data:write, sheets:read, sheets:write, and sharing:manage. Together they support the complete 78-tool catalog. They include actions that can delete model content, execute code in Bridge Town isolated compute, overwrite separately authorized Google Sheet data, and change who can access shared content.

Review Scopes and external effects before approving. Declining stops the connection. If Claude workspace policy removes a capability, Bridge Town blocks affected tools before any effect and returns the missing scope for the workspace administrator.

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_model, 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.

MCP Apps host status

Claude chat on claude.ai is tracked separately from Claude Desktop chat and Cowork. The current release-bound status is:

This status is generated from docs-site/src/data/mcp-apps-host-support.json; do not infer one Claude surface’s behavior from another.

Evidence baseline (2026-09-03): deployed source 8cb696f0a81fb4afe7c7068434e88b67acc519d0; catalog 21e339c9414143a70c061b13c43e8c44c0c7abf93b60ac1ff1fd740e3b76923d; Claude profile dddf08f3b9afa4f8b6d12580ad86886c4266f1e610277950d8818940515a93d9. The exact-release live-host gate is pending and remains owned by the release operator.

Surface	Production evidence	Interactive Apps status	Recovery limit
Claude chat (claude.ai)	Production /health matched release 8cb696f0a81fb4afe7c7068434e88b67acc519d0 and reported all 78 tools plus the catalog hash above; exact-source tests and the server canary proved all eight App bundles, static bindings, and Claude-specific resource metadata. The live-host run did not reach a tool invocation because approved browser control was unavailable.	Server delivery is proven; visible rendering of all eight Apps on this release is not yet production-proven. Earlier mixed outcomes must not be promoted to current-release support.	A new chat or connector re-add can refresh host metadata, but neither guarantees a widget. Expand the error and capture the app, time, client version, tool result, and whether resources/read occurred. Invalid ui.domain is a server-metadata defect; raw JSON alone is not a stale-session diagnosis.

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”

If the error names an insufficient-scope, ask the Claude workspace administrator to allow that capability, then reconnect and approve the complete set
Check that your Bridge Town account is active

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

Bridge Town exposes 78 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”

A raw JSON or text result does not identify the cause. Production’s scheduled canary proves the Bridge Town handshake and bundle path, but it does not prove that this Claude chat fetched or visibly rendered the App.
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.
Starting a new conversation or re-adding the connector can refresh metadata, but does not guarantee rendering. If plain-text output persists, record the app, time, Claude client version, visible error, and whether a matching resources/read occurred; continue with the complete fallback while support investigates.

“Unable to reach Bridge Town” with Invalid ui.domain format

This is different from missing App capability or an unavailable tool: the tool call completed, but Claude rejected the widget’s resource metadata.
Expand the error and record the complete Invalid ui.domain format line, the app name, and the time. Bridge Town’s Claude projection must be a bare 32-character lowercase hash followed by .claudemcpcontent.com—never an https:// URL, path, wildcard, or Bridge Town API origin.
Start a clean conversation after a deployment so Claude fetches current resource metadata. If the error persists, send the captured line to support; reconnecting alone cannot repair invalid server metadata.

Skills and connector packaging

The submitted Claude.ai connector profile contains product tools, schemas, and safe reference metadata only. It has no behavioral skill resources or prompts, and search_tools returns product tools only. This prevents a remote connector description or tool result from asking Claude to fetch and follow dynamic instructions.

The 19 Markdown files under skills/ are separately reviewed Claude Code/Desktop skill or plugin source. They are not fetched by the directory connector at runtime. See Skills and connector packaging for the package boundary and the audit table.

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