agentify-openapi

agentify

Turn any OpenAPI / Swagger spec into an agent-ready MCP server.

Listed on the official MCP Registry (io.github.sani-savaliya/agentify) and Smithery.

Point it at a spec — a URL, a file, OpenAPI 3.x or Swagger 2.0 — and every operation becomes a tool an AI agent can call. No code generation, no per-API boilerplate, no hosting. One command.

npx agentify-openapi https://petstore3.swagger.io/api/v3/openapi.json --list

Swagger Petstore - OpenAPI 3.0 v1.0.27
Base URL: https://petstore3.swagger.io/api/v3
Tools: 19

  getPetById
    Find pet by ID.
  findPetsByStatus
    Finds Pets by status.
  ...

Why

"Today, agents have to operate software designed for humans. The interfaces of the future will be built for agents — APIs, MCPs, CLIs — with agents as first-class citizens." — YC RFS: Software for Agents

There are tens of thousands of APIs that already describe themselves with an OpenAPI document. agentify makes every one of them agent-native, instantly, without anyone hand-writing an integration.

Use it with Claude, Cursor, Windsurf — any MCP client

Add it to your client's MCP config. The same command/args shape works in Claude Desktop, Claude Code (claude mcp add), Cursor (.cursor/mcp.json), Windsurf, Cline, and anything else that speaks MCP:

{
  "mcpServers": {
    "petstore": {
      "command": "npx",
      "args": ["-y", "agentify-openapi", "https://petstore3.swagger.io/api/v3/openapi.json"]
    }
  }
}

The agent now has one tool per API operation. Calling a tool builds the HTTP request (path params, query string, headers, JSON body) and returns the live response.

Big API? Pick just the tools you need

Pointing at GitHub (1000+ operations) or Stripe (400+) would flood your agent with hundreds of tools and wreck its tool-selection accuracy. Filter down to what matters — by tag, HTTP method, or name glob — and cap the total:

# GitHub, read-only, just the repo endpoints
npx agentify-openapi https://api.github.com/openapi.json --tag repos --read-only

# Stripe customer endpoints only, hard cap at 25 tools
npx agentify-openapi ./stripe.json --include "*Customer*" --max-tools 25

{
  "mcpServers": {
    "github-repos": {
      "command": "npx",
      "args": ["-y", "agentify-openapi", "https://api.github.com/openapi.json",
               "--tag", "repos", "--read-only", "--max-tools", "30"],
      "env": { "AGENTIFY_BEARER_TOKEN": "ghp_your_token" }
    }
  }
}

--read-only (GET/HEAD/OPTIONS) is also a simple safety rail — expose a giant API to an agent without exposing anything that can mutate state.

Auth

Provide credentials via environment variables — agentify reads the spec's declared security scheme to find the right header name when it can:

Variable	Effect
AGENTIFY_BEARER_TOKEN	Authorization: Bearer <token>
AGENTIFY_BASIC_USER / AGENTIFY_BASIC_PASS	HTTP basic auth
AGENTIFY_API_KEY	API key (sent as a header by default)
AGENTIFY_API_KEY_HEADER	Override the api-key header name
AGENTIFY_API_KEY_QUERY	Send the api key as a query param instead

You can also inject raw headers from the CLI: --header "X-Org-Id: 42" (repeatable).

CLI

agentify <spec-url-or-file> [options]

  --base-url <url>     Override the API base URL from the spec
  --header "K: V"      Add a raw header to every request (repeatable)
  --name <name>        Override the MCP server name
  --list               Print the discovered tools and exit (no server)
  -h, --help           Show help

  Tool selection (keep big APIs from flooding the agent's context):
  --tag <tag>          Keep only operations with this tag (repeatable)
  --exclude-tag <tag>  Drop operations with this tag (repeatable)
  --method <verb>      Keep only this HTTP method, e.g. GET (repeatable)
  --read-only          Shorthand: keep only GET/HEAD/OPTIONS operations
  --include <glob>     Keep only tools matching this glob (repeatable)
  --exclude <glob>     Drop tools matching this glob (repeatable)
  --max-tools <n>      Hard cap on tool count (warns when it truncates)

How it works

A small, pure pipeline — each stage is independently unit-tested:

spec ──▶ operations ──▶ tool defs ──▶ http request ──▶ response
 │           │              │              │              │
load &    one tool       JSON Schema   path/query/    fetch + surface
deref     per op         for inputs    header/body    status & body
$refs                                  + auth

Only the HTTP execution and MCP transport touch the outside world; everything else is deterministic and tested.

Programmatic use

import { loadSpec, extractOperations, resolveBaseUrl, createServer } from "agentify-openapi";

const spec = await loadSpec("./openapi.yaml");
const tools = extractOperations(spec);
const baseUrl = resolveBaseUrl(spec);
// ...build your own MCP server, or just inspect the generated tool defs

Limitations

• JSON request/response bodies are first-class; multipart/form bodies are passed through best-effort.
• cookie parameters and OAuth2 flows are not yet handled (use --header for now).
• One server per spec. Multi-spec aggregation is on the roadmap.

Development

npm install
npm test          # vitest, 80%+ coverage enforced
npm run build     # tsc -> dist/
node scripts/smoke.mjs   # end-to-end MCP client smoke test (network)

License

MIT