OpenAPI-to-MCP

Govern

OpenAPI-to-MCP

OpenAPI-to-MCP is constrained conversion. The gateway imports an OpenAPI document, creates candidate operations, and publishes only selected and approved mappings as MCP tools. It is not arbitrary URL routing, gRPC conversion, SOAP conversion, or a broad integration platform.

Audience

• API owners exposing a small approved operation set to agents.
• Developers checking generated tool mapping boundaries.
• Security reviewers verifying host allowlists, credential mode, size limits, and audit.

What is this?

This page documents the API adapter path. The adapter turns a selected REST operation into a generated MCP tool only after selection, approval, host allowlist, schema validation, credential binding, timeout, size, and audit checks are in place.

When do I use it?

Use OpenAPI-to-MCP when an internal API should not be exposed wholesale, but one or more operations should be callable by approved agents through the governed MCP runtime.

Good fit:

• one OpenAPI 3.x or normalized Swagger/OpenAPI 2.0 source;
• explicit allowed host refs;
• selected operations with owner review;
• first-class credential binding;
• deterministic deny reasons for unselected, unsafe, invalid, missing, oversized, or timed-out calls.

What happens?

1. The API owner imports the spec.
2. The importer detects format and candidate operations.
3. The owner selects operations and lists allowed hosts.
4. Operations that need credentials reference a credential binding.
5. Review approves the API source or selected operation mapping.
6. The generated MCP endpoint is tenant and environment scoped.
7. tools/list returns approved generated tools only.
8. tools/call validates schema, host, method/path/query/header/body mapping, credential binding, timeout, and size before upstream execution.
9. Audit records API adapter metadata, policy version, credential mode, reason code, and redaction state without request or response bodies.

What can go wrong?

• Unselected operation: operation_not_selected, no generated mapping, no upstream attempt.
• Unapproved operation: operation_not_approved, no callable tool.
• Host missing or unsafe: api_host_not_allowed, denied before upstream.
• Schema failure: schema_invalid, denied before upstream.
• Credential binding missing, denied, disabled, revoked, or unsafe: fail closed before upstream.
• Request or response size limit exceeded: denied or failed closed with safe reason metadata.
• Postman or Swagger import may normalize candidates, but auth examples and body fixtures must not leak into public docs or runtime output.

Source truth

• docs/ARCHITECTURE.md
• contracts/jsonschema/api-source.schema.json
• contracts/jsonschema/api-tool-mapping.schema.json
• contracts/openapi/admin-api.yaml

Next

• Read Identity, Policy, Credentials for credential binding and policy simulation.
• Read Runtime Architecture for where the adapter sits in the data plane.
• Read Design-Partner Pilot for a scoped API pilot shape.