npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

oag-mcp

v0.11.0

Published

Turn an OpenAPI spec and its OpenAPI Generator (OAG) typescript-fetch SDK into a code-mode MCP server at runtime

Readme

Avatar

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

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:

Colophon

Developer's Guide

Build reports: