MCP server that reads OpenAPI contracts from local (or remote) backends so agents can build frontends and mobile apps against the real API shape. By default it is read-only (inspects the OpenAPI document only). Optional HTTP execution via call_endpoint is available when you set OPENAPI_MCP_ENABLE_CALLS. Backends are registered on demand; there is no env list of backends.

Most LLMs build against APIs by guessing: inventing paths, request bodies, and response fields that may not match the backend. OpenAPI Contract MCP gives the agent a structured interface to the real OpenAPI document before any UI or client code is written.

Built with @modelcontextprotocol/sdk, it provides:

• On-demand backend registration: call use_backend with a baseUrl; nothing sensitive needs to live in a static backend list
• Contract browsing: overview, tags, operations, security schemes, and component schemas from the live spec
• Dereferenced operations: get_operation returns local $ref resolution plus a request example when possible
• Read-only by default: API execution is off unless OPENAPI_MCP_ENABLE_CALLS is set (then call_endpoint is registered)

• Node.js >= 18
• A backend that exposes OpenAPI (Nest Swagger: /docs-json, etc.)
• pnpm — only if you develop or contribute to this repo

Register the server in your MCP client's config (stdio). Shape varies slightly by client; the examples below use a common mcpServers layout.

Recommended (npm):

{
  "mcpServers": {
    "openapi-contract": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fqueis/openapi-contract"]
    }
  }
}

You can run the server from a local clone for development, but for normal use prefer the published package above.

Optional: enable HTTP calls (registers call_endpoint):

{
  "mcpServers": {
    "openapi-contract": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@fqueis/openapi-contract"],
      "env": {
        "OPENAPI_MCP_ENABLE_CALLS": "1"
      }
    }
  }
}

Prefer headerEnv (env var names) over pasting secrets into headers so tokens are less likely to appear in agent transcripts.

cd /path/to/openapi-contract
pnpm install
pnpm build
pnpm test

Built JS:

{
  "mcpServers": {
    "openapi-contract": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/openapi-contract/dist/index.js"]
    }
  }
}

Dev (TypeScript via tsx):

{
  "mcpServers": {
    "openapi-contract": {
      "type": "stdio",
      "command": "npx",
      "args": ["tsx", "/path/to/openapi-contract/src/index.ts"]
    }
  }
}

1. use_backend with baseUrl (e.g. http://localhost:3000) and optional id / specPath
2. get_api_overview / list_tags / list_operations / search_operations
3. get_operation for dereferenced schemas + request example
4. get_schema / get_security as needed
5. With OPENAPI_MCP_ENABLE_CALLS=1: call_endpoint to execute an operation (auth via headers / headerEnv)
6. forget_backend or clear_backends to drop the on-disk registry; refresh_backend to refetch OpenAPI

If baseUrl is missing, tools return a clear error so the agent can ask the user.

Default path: /docs-json. Fallbacks: /docs-yaml → /openapi.json → /v3/api-docs. Absolute document URLs are accepted.

MCP client configs (mcp.json and equivalents) pass env into the server process. Those values are always strings (same as OS/process.env). Write "1" or "30000", not bare JSON booleans or numbers.

For the communication flow between the MCP client, the service layer, the registry/cache, and the OpenAPI backend (including Mermaid diagrams), see ARCHITECT.md.

Release history lives in CHANGELOG.md. GitHub Release notes are taken from the matching version section when present.

MIT © fqueis. See LICENSE.md.