0007 — One MCP endpoint per connector; client URL needs the /mcp suffix

Status

Accepted (2026-07-09)

Context

The broker fronts many connectors but does not expose a single aggregate MCP endpoint. Each connector is served at its own path — main.py routes /proxy/{connector_name}/{path}, and a connector's streamable-HTTP MCP server lives at /proxy/<connector>/mcp. When adding the broker as a custom connector in a Claude client (claude.ai web / desktop / mobile), the URL pasted is the URL the client runs its MCP handshake against.

A connection added as https://bobsmcp.uk/proxy/gcp/ (no /mcp) completed OAuth but then failed with "your account was authorized, but no MCP server was found at the provided URL": OAuth discovery (.well-known/oauth-protected-resource/proxy/gcp) resolved, but the post-auth MCP initialize did not land on the connector's MCP endpoint. The connector code was correct all along — verified that gcp / tailscale are native connectors sharing the exact in-process dispatch path as the working notion_api. The failure was purely the client URL.

Decision

Standardize the client connector URL as https://bobsmcp.uk/proxy/<connector>/mcp — with the trailing /mcp. One custom connector is added per broker connector; there is no single URL that surfaces all of them. /health (unauthenticated) lists every registered connector; /status (broker key) lists the connected ones.

Consequences

• Adding a broker capability in a Claude client means adding a separate custom connector per path, each carrying its own audience-scoped OAuth token (mcp:proxy:<name>), so a token for one connector cannot drive another.
• Connector registrations are account-level: adding on desktop auto-mirrors to the Claude mobile app — no per-device setup.
• This is a client-URL / discoverability fact, not a code change; recorded here because the missing /mcp cost real debugging time.