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 = adminorpermission = advisormay 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.
| Environment | MCP server URL |
|---|---|
| Production | https://surplus.sharingexcess.com/mcp |
| Staging | https://surplus.staging.sharingexcess.com/mcp |
| Dev environment | https://surplus.dev-{feature}.sharingexcess.com/mcp |
| Local | http://localhost:{PUBLIC_WEB_PORT}/mcp |
| Path | Role |
|---|---|
/mcp | Resource 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
- An MCP request without a token gets
401with aWWW-Authenticateheader pointing at the protected resource metadata,{APP_URL}/.well-known/oauth-protected-resource/mcp(RFC 9728). - The client reads it, then the authorization server's metadata at
{APP_URL}/.well-known/oauth-authorization-server. - The client sends the browser to
/auth/oauth2/authorizewith its Client ID Metadata Document URL asclient_id, a PKCES256challenge, andresource={MCP_SERVER_URL}. - 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.
- The client exchanges the authorization code and its PKCE verifier at
/auth/oauth2/tokenfor an access token (15 minutes,aud= the MCP server) and a refresh token (30 days, replaced on every use). - 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-hocSELECTqueries 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/WITHstatement 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:
| URI | Purpose |
|---|---|
surplus://schema/dbml | Database schema (camelCase) |
surplus://guide/terminology | User language → Surplus terms |
surplus://guide/overview | Domain overview |
surplus://guide/sql | SQL patterns for run_read_query |
surplus://guide/analytics | Impact / holding-partner semantics |
surplus://guide/statuses | Status 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.
| App | Surfaces | Redirect |
|---|---|---|
| Claude | claude.ai, the Claude desktop and mobile apps, Cowork | https://claude.ai/api/mcp/auth_callback |
| Claude Code | The CLI, the Claude desktop app's Code tab, IDE extensions | http://localhost or http://127.0.0.1, any port |
| ChatGPT | chatgpt.com, the ChatGPT desktop and mobile apps | https://chatgpt.com/connector_platform_oauth_redirect |
| Codex | The CLI, the IDE extension, the desktop app | http://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
- Add a custom connector with your environment's
MCP_SERVER_URL(including/mcp— match exactly), or in Claude Code runclaude mcp add --transport http surplus <MCP_SERVER_URL>. - 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.
Related
- 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
