For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /reference/docs/decisions/0071-generated-mcp-api-edge.md.

0071 — Generated MCP access to the Go API

Status: Proposed for the experimental/mcp branch.

Context

Shared MCP clients need the platform's read and write API, authenticated through AAI. The historical architecture-reset implementation separated the MCP gateway, OAuth broker and API assertions. The current API uses canonical Party identity, current authentication generations and context-owned commands.

Decision

Keep MCP within the API service boundary, with two separate processes:

  • A native Go gateway uses the official MCP SDK's stateless Streamable HTTP transport and a generated Go API client.
  • An OAuth broker adapts the historical oidc-provider implementation. It federates to the configured AAI issuer and owns private technical OAuth state in a separate PostgreSQL database with restricted runtime credentials.

The MCP contract owns the reviewed operation manifest, schemas, scopes and private assertion protocol. OpenAPI remains the authority for business paths, inputs and responses. Generation covers every business operation, including commands and deletions. API additions and removals require an explicit parity review. Authentication callbacks, internal relays, diagnostics and realtime transports are outside the business tool catalogue.

The gateway has no business database, broker, operator-key or provider access. Every invocation crosses the existing HTTP bindings and owner authorisation. Command headers, input, revisions and pagination remain intact. The gateway never retries a business request automatically.

AAI login requires the exact verified issuer, subject and voperson_id. A distinct broker login assertion asks the API to resolve an existing Party, current AUP and its current authentication generation. This query cannot register, adopt or recover a Party. OAuth accounts and grants retain that generation immutably. Refresh and business calls recheck current authority. Browser logout retains its own session semantics; Party disablement and generation changes fence both access routes.

Access tokens target only the MCP resource. The gateway exchanges their verified identity for a short-lived, operation-bound API assertion signed by a different key. The API rejects a direct MCP access token. Public keys for the broker and gateway must be distinct.

Resource scopes separate each owner's reads and writes. Explicit consent names the client and scopes. Operator-only Support routes also require a canonical Party enrolled in API_MCP_OPERATOR_PARTIES; the default is empty. A scope or AAI attribute alone cannot grant operator authority.

Consequences

The Go gateway is stateless and supports independent replicas. The broker needs its private database, persistent signing and cookie keys, a registered AAI client, HTTPS routing and operational key rotation. Retaining an established OAuth library adds a Node process alongside the Go API.

The optional laboratory profile activates these processes explicitly on development boxes with local AAI. Other deployments keep the experiment disabled. The runtime guide records enrolment and qualification. Source and disposable fixture checks establish the protocol boundaries; external AAI, actual MCP clients and deployed business journeys require separate qualification.

Page source

Source snapshot · Revision f928834c8.