OAG-MCP

OAG-MCP turns an OpenAPI specification and its OpenAPI Generator (OAG) SDK into a code-mode MCP server at runtime.

Instead of exposing hundreds of endpoints as individual tools, it exposes two:

• search for discovering operations from the spec.
• execute for running agent-written code against your SDK in a sandbox.

The SDK stays on the host with your credentials, which are applied from the spec’s security schemes, so secrets never enter the sandbox.

Point OAG-MCP at a spec and an SDK, and your whole API is agent-ready in under a thousand tokens of context.

oag-mcp serve --spec ./openapi.yaml --sdk ./generated-sdk --transport streamable-http --port 3000
Copy

https://github.com/user-attachments/assets/93b462db-4ff8-4b22-8dfd-120daa0855c9

Why OAG-MCP

A lot of OpenAPI-to-MCP bridges expose one MCP tool per endpoint, or a generic HTTP request tool. OAG-MCP takes a different approach by utilising SDK-backed code mode where the SDK is generated out of the OpenAPI specification itself:

• OpenAPI supplies the contract and documentation: descriptions, tags, parameters, schemas, examples and security requirements.
• The generated typescript-fetch SDK supplies the callable interface: the exact classes, methods, signatures and model types.
• search discovers relevant SDK methods with their signatures, referenced types, auth requirements and a ready-to-run example.
• execute runs agent-written TypeScript that composes real SDK calls — loops, filtering, aggregation, Promise.all — inside an isolated Deno sandbox, and returns only the compact result.
• The SDK stays an ordinary package that your applications, CLIs, and other consumers keep using directly; OAG-MCP only reads it.
• MCP sees two tools, not one per endpoint, so large APIs don't flood the agent's context.

Letting an AI agent write code against a real API is only useful if it is safe. OAG-MCP is built security-first: it treats agent code as untrusted and keeps your credentials out of its reach, so you can give an agent your API without giving it your keys or your infrastructure:

• Credentials never reach the agent: secrets are loaded only at run time, added to requests by OAG-MCP's broker outside the sandbox, and scrubbed from logs, errors and results.
• Agent code runs in a locked-down sandbox: a fresh Deno process per call, with no file system, network, environment or subprocess access, no eval, and limits on time, memory, output and API calls.
• Every API call is checked: the broker allows a request only if it matches the operation it claims to be, on the configured API, for a caller the authorisation rules allow; a deny always wins.
• No unauthenticated remote access: over HTTP, every request must carry a valid bearer or OAuth 2.0 access token; serving without one is allowed only on loopback. Over stdio, only the process that started OAG-MCP can reach it. Either way each caller gets an identity for authorisation and audit, and an MCP token is never forwarded to your API.
• Safe by default: it binds to loopback, refuses to serve a non-loopback address without authentication, checks Host and Origin, and never runs the SDK's code or install scripts on the host.
• Everything is audited: every security decision is a standard OCSF event, ready for a SIEM, with an option to stop executing while audit records cannot be written.

Security describes each protection, and what is not claimed.

Installation

npm install -g oag-mcp
Copy

Requirements

• Node.js 22+ - For running the oag-mcp command.
• Deno 2.5 or later (2.x) - Installed automatically through the deno npm dependency; or set OAG_MCP_DENO_PATH / put deno on PATH.
• OpenAPI specification
• An SDK generated with OpenAPI Generator's typescript-fetch.

Quick start

1. Generate a typescript-fetch SDK

Generate the typescript-fetch SDK from your OpenAPI specification with OpenAPI Generator's official Docker image:

# Name your OpenAPI specification openapi.yaml
# and place it on your current working directory.

docker run --rm -v "$PWD":/local openapitools/openapi-generator-cli:v7.26.0 \
  generate \
  --input-spec /local/openapi.yaml \
  --generator-name typescript-fetch \
  --output /local/generated-sdk
Copy

The generated SDK code on that directory ./generated-sdk can be used directly and you're done for step 1.

However, as an alternative, you can also use an npm archive packed from the generated SDK code.

2. Run the MCP server

# stdio
oag-mcp serve --spec ./openapi.yaml --sdk ./generated-sdk --transport stdio

# Streamable HTTP
oag-mcp serve --spec ./openapi.yaml --sdk ./generated-sdk \
  --transport streamable-http --port 3000

# from a packaged SDK
oag-mcp serve --spec ./openapi.yaml --sdk ./petstore-sdk-1.0.0.tgz --transport stdio
Copy

On start-up OAG-MCP checks that the SDK is compatible, prepares it for the sandbox and indexes its methods — typically in one to a few seconds — and only then accepts MCP requests. If anything cannot be prepared, it exits with an error code and a hint explaining what to fix, rather than starting a partially working server.

Example MCP client entry (stdio):

{
  "mcpServers": {
    "petstore": {
      "command": "oag-mcp",
      "args": [
        "serve", "--spec", "/path/to/openapi.yaml", "--sdk", "/path/to/generated-sdk",
        "--transport", "stdio", "--config", "/path/to/oag-mcp.config.yaml"
      ],
      "env": { "PETSTORE_API_KEY": "…" }
    }
  }
}
Copy

3. Configure credentials and access

Create OAG-MCP configuration file:

# oag-mcp.config.yaml — contains references to secrets, never secret values
upstream:
  # default: the spec's first server URL, which must be absolute
  baseUrl: https://api.example.com/v1
upstreamAuth:
  schemes:
    apiKeyHeader:
      # security scheme name from the OpenAPI document
      apiKey: { env: PETSTORE_API_KEY }
Copy

Run MCP server with the configuration file passed as --config arg:

oag-mcp serve --spec ./openapi.yaml --sdk ./generated-sdk --config ./oag-mcp.config.yaml
Copy

Secrets are resolved at start-up from environment variables or a 0600 secrets file. They are never accepted as CLI arguments and never written to the method index, the prepared SDK bundle, logs or anything agent code can read. See authentication for MCP access control (mcpAuth) and upstream credentials (upstreamAuth), authorisation for per-operation permissions, and the configuration reference for every option.

Learn more

• How it works — what happens, step by step, from start-up to each tool call
• SDK compatibility — supported versions, options, package layouts, dependencies
• Architecture — components, start-up preparation, execution model, design choices
• Decision records — why OAG-MCP is built the way it is
• Security — OAG-MCP's security features, and what is not claimed
• Authentication — who may call OAG-MCP (mcpAuth), and how it calls your API (upstreamAuth)
• Authorisation — what each caller may do (authorization)
• Identity — how the agent, OAG-MCP and the API are identified, and how to trace a call through the logs
• Logging — operational records (OpenTelemetry) and security audit records (OCSF)
• Deployment — running OAG-MCP as a server, in a container and in production
• Troubleshooting — why OAG-MCP does not start, a client cannot connect, or a call failed
• Testing — lint checks, unit and integration tests, and extra checks
• Releasing — for maintainers: packaging and publishing OAG-MCP
• Recipes — set-ups for common situations, from configuration to logs:
  • Read-only server — try OAG-MCP safely, reading but not changing anything
  • Upstream credentials — API keys, bearer tokens and basic authentication
  • Upstream OAuth2 — OAuth2 client credentials tokens
  • Curated operations — expose only some of an API
  • Per-caller permissions — give each caller its own operations
  • Execution limits — tune time, memory, result and API-call limits
  • Remote server — serve remote MCP clients over HTTPS
  • Packaged SDK — deploy the SDK as a versioned archive
  • Audit logging — keep security audit records in a file, a log shipper or a SIEM
• Reference — everything OAG-MCP accepts and produces:
  • MCP tools — the search and execute tools
  • CLI — the serve command, its flags and environment variables
  • Configuration — every configuration property
  • HTTP endpoints — paths, request checks and responses
  • Error codes — why OAG-MCP did not start
  • Error types — errors execute returns to the agent
  • Log events — every operational and security audit record

Colophon

Developer's Guide

Build reports:

• Code complexity report
• Unit tests report
• Test coverage report
• Integration tests report
• API Documentation