MCP platform contract
Status and scope
| Field | State |
|---|---|
| Contract status | Current master; V1 retirement gates remain open |
| Implementation status | V2 maintained; V1 compatibility retained |
| Last source review | 2026-08-26 |
| Runtime verification | Required for callers, OAuth, values, and telemetry |
| Owner | Not recorded in this public document |
MCP V2 is the maintained Streamable HTTP interface at /api/mcp. V1 remains a compatibility surface until every exit criterion below is verified. This master replaces separate developer-guide, parity-test, usage-replay, tool-inventory, and retirement-audit pages.
Canonical implementation
| Concern | Source |
|---|---|
| HTTP entrypoint | src/app/api/mcp/ |
| MCP domains/tools | src/mcp/ |
| Tenant query rules | src/lib/auth-scope.ts and called reporting services |
| Operational surface | /admin/mcp |
Tool names and counts are generated implementation details. Discover them from the running server or source registry; do not maintain a copied count in documentation.
Connection and support contract
- Use Streamable HTTP at the deployment's
/api/mcpendpoint. - Use OAuth 2.1 for governed clients. Legacy static-token behavior is temporary compatibility, not the target contract.
- Unknown or unauthorized tenant hints fail closed. Tenant-locked callers cannot expand scope by supplying another client.
- A tool is supported only when its handler, authorization boundary, data path, tests, and representative runtime output are verified.
- Output-shape parity is separate from value parity. Matching keys do not prove matching data.
V1 retirement decision
Do not retire V1 until every following acceptance gate has dated evidence: known callers have migrated; caller telemetry establishes that no required V1 traffic remains; V2 covers every required workflow; tenant and permission behavior passes adversarial tests; representative values match under the same source window and denominator; OAuth onboarding and refresh work; production telemetry is observable; and rollback is proven with an explicit owner. No current caller-telemetry conclusion is established by this master document.
See the V1 retirement runbook for the executable checklist.
Verification
- Discover the current registry from the target environment.
- Run authenticated checks for representative reporting, entity, and diagnostic tools.
- Confirm tenant isolation with allowed, forbidden, and unknown tenant cases.
- Compare output shapes and values separately.
- Record target, deployment, source window, caller class, and limitations.
Local no-credential or replay checks prove mechanics only. They do not satisfy live value or OAuth gates.
Provenance
| Replaced document | Contribution retained here |
|---|---|
| MCP V2 developer guide | Connection, support-level, migration, and data-path contract |
| MCP V1 retirement audit — 2026-08-17 | Standing decision and retirement criteria |
| MCP V1 usage + V2 replay — 2026-08-16 | Usage and expanded-output evidence model |
| MCP V1/V2 parity audit — 2026-08-16 | Shape/value separation and live-value gate |
| Sprint 6 MCP parity test — 2026-08-07 | Early mapping evidence; historical only |
| Sprint 6 MCP tool inventory | Historical inventory; current inventory is generated |
| Sprint 6 kickoff plan | Original delivery context; no longer active |