oag-mcp
Turn an OpenAPI spec and its OpenAPI Generator (OAG) typescript-fetch SDK into a code-mode MCP server at runtime
Install / Use
claude mcp add oapicf -- npx -y github:oapicf/oag-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of oag-mcp
oag-mcp scores 71/100 on our quality scale, 3867th of 4,722 Development & Engineering skills we index.
Its MCP Server is 11 KB long, well organised into 16 sections with 7 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 2 days ago, so oag-mcp is actively maintained.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
oag-mcp compared with similar skills
All 4 of these similar skills score higher than oag-mcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| oag-mcp (this skill)by oapicf | 71 | 3 | 2d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 118.3k | 10d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 113.0k | 10d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 86.4k | today | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
Frequently asked questions
- How do I install oag-mcp?
- Run
claude mcp add oapicf -- npx -y github:oapicf/oag-mcp. The install tabs above show the steps for each supported agent. - Which AI agents does oag-mcp work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is oag-mcp safe to use?
- It is Apache-2.0-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is oag-mcp still maintained?
- The repository was last updated 2 days ago, so oag-mcp is actively maintained.
Skill content
View source on GitHub![]()
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:
searchfor discovering operations from the spec.executefor 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
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.
searchdiscovers relevant SDK methods with their signatures, referenced types, auth requirements and a ready-to-run example.executeruns 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
HostandOrigin, 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
Requirements
- Node.js 22+ - For running the
oag-mcpcommand. - Deno 2.5 or later (2.x) - Installed automatically through the
denonpm dependency; or setOAG_MCP_DENO_PATH/ putdenoonPATH. - 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
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
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": "…" }
}
}
}
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 }
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
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
searchandexecutetools - CLI — the
servecommand, 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
executereturns to the agent - Log events — every operational and security audit record
- MCP tools — the
Colophon
<!-- BEGIN:DEVELOPERS_GUIDE --> <!-- END:DEVELOPERS_GUIDE --> <!-- BEGIN:BUILD_REPORTS -->Build reports:
<!-- END:BUILD_REPORTS -->Related Skills
taste-skill
118.3kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
113.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
hyperframes
86.4kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
