MCP integration

Surplus exposes a read-only MCP server for admin and advisor accounts. Claude, Claude Code, ChatGPT, and Codex authenticate via OAuth 2.1 and call curated tools backed by the same data layer as the web app.

Admin and advisor only. MCP rejects driver, partner, and suspended users with 403. Only accounts with permission = admin or permission = advisor may call tools.

Server URL

The MCP server is part of the Surplus web app: its URL (MCP_SERVER_URL below) is the app's own URL (APP_URL) followed by /mcp. The same app is the OAuth authorization server.

EnvironmentMCP server URL
Productionhttps://surplus.sharingexcess.com/mcp
Staginghttps://surplus.staging.sharingexcess.com/mcp
Dev environmenthttps://surplus.dev-{feature}.sharingexcess.com/mcp
Localhttp://localhost:{PUBLIC_WEB_PORT}/mcp
PathRole
/mcpResource server — validates Bearer tokens, serves read-only tools
/auth/oauth2/*OAuth 2.1 authorization server — email sign-in code during authorize, token issuance

OAuth flow

  1. An MCP request without a token gets 401 with a WWW-Authenticate header pointing at the protected resource metadata, {APP_URL}/.well-known/oauth-protected-resource/mcp (RFC 9728).
  2. The client reads it, then the authorization server's metadata at {APP_URL}/.well-known/oauth-authorization-server.
  3. The client sends the browser to /auth/oauth2/authorize with its Client ID Metadata Document URL as client_id, a PKCE S256 challenge, and resource={MCP_SERVER_URL}.
  4. The user signs in with an emailed code (the same accounts as the web app) and approves. The page names the app, the host of its metadata document, and the host it will return to.
  5. The client exchanges the authorization code and its PKCE verifier at /auth/oauth2/token for an access token (15 minutes, aud = the MCP server) and a refresh token (30 days, replaced on every use).
  6. MCP requests include Authorization: Bearer …. The MCP server verifies the token's signature with the app's public keys (published at /auth/jwks), then checks the user's permission in the database on every request.

There are no scopes. A token says who the user is; what they may do comes from their account, so an admin or advisor sees the tools and anyone else is refused. The web app's own pages sign in through the same endpoints, with a session cookie instead of a bearer token.

Tools

The MCP server exposes 24 read-only tools:

  • 23 curated tools — impact analytics, organization search, operational inventory, events, routes, users
  • run_read_query — ad-hoc SELECT queries against a read replica

Curated tools return paginated results with the true total alongside each page. run_read_query enforces:

  • Read-only database role with no access to auth/OAuth tables
  • Single SELECT/WITH statement only; write keywords and privileged functions blocked
  • 30-second statement timeout; 5,000-row return ceiling (errors rather than silent truncation)

Every tool call requires an _intent block (paraphrasedOriginalUserPrompt, currentSpecificAgentQuestion, optional sessionId). Server instructions on initialize document the requirement.

Resources

On initialize, clients also receive six resources:

URIPurpose
surplus://schema/dbmlDatabase schema (camelCase)
surplus://guide/terminologyUser language → Surplus terms
surplus://guide/overviewDomain overview
surplus://guide/sqlSQL patterns for run_read_query
surplus://guide/analyticsImpact / holding-partner semantics
surplus://guide/statusesStatus enums and tool picks

Supported clients

The authorization server accepts only Anthropic's and OpenAI's apps. Each identifies itself with a Client ID Metadata Document (CIMD): its client_id is an HTTPS URL it hosts, which the authorization server fetches to learn its name and redirect URIs. There is no registration endpoint, so no other client can connect.

AppSurfacesRedirect
Claudeclaude.ai, the Claude desktop and mobile apps, Coworkhttps://claude.ai/api/mcp/auth_callback
Claude CodeThe CLI, the Claude desktop app's Code tab, IDE extensionshttp://localhost or http://127.0.0.1, any port
ChatGPTchatgpt.com, the ChatGPT desktop and mobile appshttps://chatgpt.com/connector_platform_oauth_redirect
CodexThe CLI, the IDE extension, the desktop apphttp://127.0.0.1 or http://localhost, any port

Metadata documents must be on claude.ai, claude.com, or chatgpt.com, and a redirect URI must be one the client's own document lists. Loopback redirects are accepted only for Claude Code's and Codex's documents. The rules are the same in every environment.

In every client, sign in with the emailed code in the Surplus web app when prompted. Your account must be admin or advisor. Clients refresh their tokens on their own; if a refresh token stops working, the client asks you to connect again.

Claude and Claude Code

  1. Add a custom connector with your environment's MCP_SERVER_URL (including /mcp — match exactly), or in Claude Code run claude mcp add --transport http surplus <MCP_SERVER_URL>.
  2. Leave the optional Client ID field empty.

ChatGPT

Add the MCP server as a connector with your environment's MCP_SERVER_URL, and choose OAuth. ChatGPT finds the authorization server and uses its Client ID Metadata Document on its own.

Codex

Run codex mcp add surplus --url <MCP_SERVER_URL>, then codex mcp login surplus, or add the server under MCP servers in the IDE extension or desktop app and select Authenticate.

For local MCP development against this repo, run the web app (bun dev --env dev-{feature}) and connect Claude Code or Codex to http://localhost:{PUBLIC_WEB_PORT}/mcp, or to your dev environment's host's /mcp.

  • Domain model — entities referenced by tools
  • Access control — web app auth and roles (MCP uses OAuth, not cookies)
  • App API — how the web app's own server calls work