> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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](/reference/contracts/mcp/README.md) 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 <a href="/source/gitops/manifests/mcp/README.md.txt">laboratory profile</a> activates
these processes explicitly on development boxes with local AAI. Other deployments
keep the experiment disabled. The [runtime guide](/reference/services/api/services/mcp/README.md)
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.

<details class="page-source"><summary>Page source</summary>

<a href="/source/docs/decisions/0071-generated-mcp-api-edge.md.txt">Source snapshot</a> · Revision `f928834c8`.

</details>