Platform contracts (mcp-contracts 7.0.0)

mcp-contracts is the machine-readable form of the interfaces between the platform’s components: OpenAPI 3.1, JSON Schema 2020-12, the Cedar schema, test keys, test vectors and mocks. Current version: 7.0.0. It is a library for authors of platform components and MCP servers, not something you run. The contracts are frozen: a change is proposed in CONTRACT_CHANGES.md of the repository and approved by a person.

The contracts

Id	What it defines	File
C1	Token of the AI client at the gateway (OAuth, identity provider token)	test-vectors/gateway-authentication/, test-vectors/oauth-metadata/
C2	Internal JWT the gateway sends to servers and the broker	schemas/internal-jwt.schema.json, test-vectors/jwt/
C3	Credential headers X-MCP-Credential and X-MCP-Credential-Type	openapi/mcp-server.v1.yaml, test-vectors/credential-type-header/
C4	Credential broker API	openapi/credential-broker.v1.yaml
C5	Gateway admin API (servers, policies, approvals)	openapi/gateway-admin.v1.yaml
C6	Server manifest: tools, risk, resource types, policies	schemas/server-manifest.schema.json, test-vectors/manifests/, test-vectors/definition-hash/
C7	Cedar model, policies and the policy data the gateway pushes	cedar/mcp.cedarschema, cedar/platform/, cedar/examples/
C8	Audit event	schemas/audit-event.schema.json, test-vectors/audit-events/
C9	Group names (mcp-<system>-read and so on)	schemas/common.schema.json#/$defs/GroupName
C10	Tool errors	schemas/tool-error.schema.json, test-vectors/tool-errors/
C11	Confirmation of destructive calls with a one-time code	test-vectors/confirmation-binding/, test-vectors/totp/
C12	Portal BFF API	openapi/portal-bff.v1.yaml
C13	Port to an access governance (IGA) system	described in the repository README

The server-facing interface that connects a server to the gateway is C14, openapi/mcp-server.v1.yaml: GET /.well-known/mcp-manifest, POST /.well-known/mcp-policy-data and the gateway’s public key set GET /.well-known/mcp-jwks.json.

For a server author the ones that matter are C2, C3, C6, C7, C10 and C14. The starter implements them; read the schemas when you write a client, a mock or a test of your own.

Get the artifacts

Maven Central, group pl.aiwcorpo.mcp. No repository entry and no credentials are needed.

Coordinates	Contents
pl.aiwcorpo.mcp:mcp-contracts:7.0.0	OpenAPI, schemas and Cedar files as classpath resources under mcp-contracts/
pl.aiwcorpo.mcp:mcp-contracts:7.0.0:test-vectors	Test vectors and test keys. Test scope only
pl.aiwcorpo.mcp:mcp-cedar-entities:7.0.0	Cedar entity builder and validation of policy fragments
pl.aiwcorpo.mcp:mcp-manifest:7.0.0	definitionHash and the manifest rules
@aiwcorpo/mcp-contracts@7.0.0 (npm)	The same files plus TypeScript types and MSW handlers

<dependency>
  <groupId>pl.aiwcorpo.mcp</groupId>
  <artifactId>mcp-contracts</artifactId>
  <version>7.0.0</version>
</dependency>
<dependency>
  <groupId>pl.aiwcorpo.mcp</groupId>
  <artifactId>mcp-contracts</artifactId>
  <version>7.0.0</version>
  <classifier>test-vectors</classifier>
  <scope>test</scope>
</dependency>

npm install --save-dev @aiwcorpo/mcp-contracts@7.0.0

A server written with the starter gets the contracts through the starter’s BOM, so it does not declare them itself. Read a file from the classpath with getResource("/mcp-contracts/schemas/internal-jwt.schema.json"). The npm package exports @aiwcorpo/mcp-contracts/msw, .../types/portal-bff, .../openapi/*, .../schemas/* and .../test-vectors/*.

Test vectors

test-vectors/ holds input and expected result for every rule that a schema cannot express. A receiver passes when it gives the same result and reason for each file. The groups a server author uses:

Directory	Tests
jwt/	Every accept and reject case of the internal JWT
manifests/, definition-hash/	Manifest validity and the hash the gateway pins
tool-errors/	Valid and invalid C10 errors
credential-type-header/	Credential type in the header against the server’s configuration
policy-decisions/, entity-builder/	Cedar requests and their decisions

The private test keys in test-vectors/keys/ are public by design and marked NOT-FOR-PRODUCTION. Servers reject them outside the dev and devstack profiles. mcp-platform-test from the starter signs tokens with them, so most servers never use the vectors directly.

Versions

The version applies to the jars, the npm package and the git tag at once. Since 2.0.0 the numbering is SemVer: a removed field or a stricter validation is a major version. Release 7.0.0 turned systems, servers and resource types from fixed lists into runtime data, which is why a new system needs no change in the contracts. Per-release changes are in CHANGELOG.md of the repository.