SkillAgentSearch skills...

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-mcp

If the server publishes to npm under a different name, use that package instead — check the repo README.

About this skill
🔌

MCP Server

Model Context Protocol server

Quality Score

71/100

Supported Platforms

Claude Code
Claude Desktop

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.

Substance
29/30
Structure
20/20
Description
12/15
Adoption
3/20
Freshness
15/15

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.

SkillScoreStarsUpdatedFormat
oag-mcp (this skill)by oapicf7132d agoMCP Server
taste-skillby Leonxlnx100118.3k10d agoCLAUDE.md
Agent-Reachby Panniantong100113.0k10d agoCLAUDE.md
hyperframesby heygen-com10086.4ktodayCLAUDE.md
rufloby ruvnet10082.0ktodayCLAUDE.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.
<!-- BEGIN:AVATAR -->

Avatar

<!-- END:AVATAR --> <!-- BEGIN:BADGES -->

Build Status Dependencies Status Code Scanning Status Coverage Status Security Status Published Version

<!-- END:BADGES -->

M8ven Score

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

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

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

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:
  • 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

<!-- BEGIN:DEVELOPERS_GUIDE -->

Developer's Guide

<!-- END:DEVELOPERS_GUIDE --> <!-- BEGIN:BUILD_REPORTS -->

Build reports:

<!-- END:BUILD_REPORTS -->

Related Skills

View on GitHub
GitHub Stars3
CategoryDevelopment
Updated2d ago
Forks0

Languages

TypeScript

Trust signals

92/100

From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.

1 low
oag-mcp — MCP Server: Install & Safety Check | SkillAgent