Architecture Decision Records
ADR 0041: Platform API Tokens and the MCP Service Share One Credential
On this page
Date: 2026-10-11 · Status: Accepted
Context
The management API accepts only login sessions (JWT or Cookie, expiring after 24 hours), leaving scripts and external AI tools without a long-lived, revocable credential. Existing API keys (gw-) are used only for the /v1 inference gateway and do not represent a user.
The AI assistant's tools now read platform APIs as the user asking the question (aihelper.APIReader). The same tools are suitable for exposing to external tools such as Claude Code and Cursor through MCP, but require a credential that can represent a user.
Decision
- Add platform API tokens, separate from inference API keys: the plaintext starts with
gwp_(256 random bits); store only its SHA-256 and a display prefix in a separateplatform_tokenstable. The random string has enough entropy to avoid argon2; each request requires one indexed lookup. - Use the same token for both management APIs and MCP, without a separate MCP credential.
- A token represents its creator: authorize every request against the user's current role in the user table, then apply the token scope:
read(GET/HEAD andPOST /api/v1/mcp) orwrite(the same access as a login). The default isread. - No token can manage tokens (
/api/v1/platform-tokensaccepts login sessions only), preventing a read-only token from issuing itself a read/write token. - Parse authentication once in the outer
managementAuthlayer and place the identity in the request context;claimsFromRequestreads the context first, while its callers andmanagementAdminremain unchanged. Routes declare token scope instead of middleware checking paths: attachsessionOnlyto token management endpoints andreadTokensReadto the other management routes, but not toPOST /api/v1/mcp(the tools are read-only). - MCP uses Streamable HTTP and returns JSON only: the protocol lives in the leaf package
internal/server/mcp, which depends on no other package in this repository. The tools areaihelper.BuiltinTools(), sharingTool.Runwith the agent loop (the same errors and truncation). They read APIs as the caller throughAPIReaderand are read-only regardless of token scope. An administrator controls the switch, which is off by default. - Cache validation results briefly (1 minute, keyed by token hash): previously, every token-bearing request read both the token row and the user row, and each MCP read required another validation. Revocation through this store takes effect immediately, and a read concurrent with revocation cannot put a revoked token back into the cache.
Tradeoffs
- Do not reuse the
api_keystable by adding a “purpose” column: inference keys do not belong to users and sit on the gateway's hot path with argon2 and caching, while management tokens must bind to users and scopes. Combining them would compromise both semantics and performance choices. - Do not implement fine-grained permissions (per resource or endpoint): the platform has only admin / user roles, and two scope levels already cover “read-only access for AI tools” and “read/write access for automation scripts.” Extend
scopeif needed. - Do not enable SSE streaming: all tools perform one-shot reads, so JSON responses suffice and no sessions need to be maintained.
- Revocation deletes the token without retaining a revocation record; auditing relies on slog entries for creation, revocation, and MCP tool calls.
Consequences
- A new table and migration 137; setting key
mcp.enabled; one more package dependency forapi(mcp, architecture budgetapi_fanout39→40). - Documentation: Connect Through MCP, API Reference: Platform Tokens.
Was this page helpful?