mcpify

mcpify

English | Türkçe

Turn any OpenAPI REST API into an [MCP](https://modelcontextprotocol.io) server — so Claude Code, Cursor, and every other MCP client can call your API directly. One command, zero runtime dependencies:

mcpify serve https://your-company.com/openapi.json

# try it right now, nothing installed (uvx pulls from PyPI on demand)

uvx --from mcpify-openapi mcpify list examples/petstore.json --cost

Focused, production-ready, CLI-first: one job (OpenAPI → MCP). Everything else — governance, credentials, token economics, operations — is opt-in and stays out of the way until you need it:

• Safe for agents by default — lazy context budget (--lazy), secret masking (--redact), blast-radius limits (--read-only, per-token RBAC)
• Ready for real deployments — stdio + HTTP/SSE, OAuth2 and split read/write credentials, health probes, audit trail, metrics, multi-API serving, hot reload
• Proven, not promised — 520 tests across twenty-eight suites, a hostile-spec corpus, live-CI checks, zero runtime dependencies

Why you'll like it

From spec to server

• 60 seconds to working — point it at any OpenAPI 3.x spec (file or URL)
• Every operation becomes a first-class MCP tool — input schemas are generated from parameters + requestBody, internal $refs are resolved
• Spec versions diffed from the tool view — mcpify diff old.yaml new.yaml reports added/removed/changed operations with per-change breaking verdicts and a migration guide; --fail-on-breaking is a CI gate
• `mcpify doctor` — tells you if your spec is agent-friendly before you ship: missing operationIds, missing summaries, instruction-like tool text, overlong descriptions; --probe dials the API once — with your real credential (--auth-env) when you want auth proven end-to-end, and --fail-on-http-error for a strict CI gate
• `mcpify try` / `mcpify mock` / `mcpify output-server` — call the tools without an agent client, serve a schema-shaped fake API for CI, or bake a serve command into a shareable script

Credentials & policy

• Credentials never touch the spec or the model — pulled from your environment at call time; the spec's own security declarations pick the flags (bearer, basic, header, query)
• OAuth2 client-credentials built in — tokens are fetched, cached, refreshed and re-fetched on a mid-flight 401 (RFC 6749, stdlib only); --write-oauth2-* gives non-GET calls a second client identity so reads and writes authenticate as different clients
• Least-privilege by default — --write-auth-env splits the static credential (reads on your read key, writes on a dedicated key), --read-only filters the surface, --deny/--allow hides mutating GETs, per-token RBAC gives each bearer token its own allow/deny scopes
• `--redact password,token` — values whose key names a secret are masked with *** at every level of every response (error bodies included, case-insensitive); the model never sees them
• Audit trail without content exposure — one JSON line per call: tool, API, status, latency, an argument *fingerprint* (never raw arguments); --plugin loads your Python module for auth/request/result hooks

Token economics

• See the bill before serving — mcpify list --cost prices the surface (~4 chars/token): what every agent pays in EVERY tools/list; multi-API configs get per-API and total prices in one run
• `--fields id,event` — response projection that selects at every level: selected keys keep their value, non-selected containers stay transparent, emptied containers drop. Live weather.gov: 350 alerts in full inside the budget that previously truncated at ~189
• Valid truncation — oversized responses are cut along JSON structure with an explicit "truncated": true marker, never mid-document
• `--lazy` search-then-call — cut api.weather.gov's listing by 95.5%; search results now show what pulling each full schema would cost, so the agent pulls only what it needs
• `[tool-text]` overrides — doctor flags model-facing instruction-like descriptions; you replace them per tool in config

Operations

• Two transports, one tool surface — stdio for local agents; serve --http 8080 speaks MCP Streamable HTTP (SSE responses for clients that ask, JSON otherwise) so a whole team shares one server, with optional bearer tokens
• Several APIs, one MCP server — [apis.NAME] sections in .mcpify.toml: per-API auth, caching, retries, filters and rate limits; collision-safe renames; aggregated health; mcpify status probes every API in parallel
• Upstream courtesy built in — ETag-aware caching, idempotent-only retries (502/503/504), --wait-on-429 honors Retry-After, --rate-limit RPS caps requests/second (per upstream in multi-API, retries included)
• Observability, opt-in only — Prometheus --metrics (call counters, latencies, cache, health — plus projection/redaction counters when those run), --otel spans, --reload hot swap, mcpify ui local dashboard
• Host it yourself for free — docker-compose with automatic-HTTPS Caddy plus a hardened systemd unit: Self-hosting guide
• Zero runtime dependencies — the entire tree is auditable stdlib Python; YAML specs need an optional pip install 'mcpify[yaml]'

Quick start

# install (installs the `mcpify` command)

pipx install mcpify-openapi

run without installing (uvx — pulls from PyPI on demand)

uvx --from mcpify-openapi mcpify list ./openapi.json --read-only

first time? the wizard writes a config for you

uvx --from mcpify-openapi mcpify init

...as a container (GHCR, published on every release)

docker run -i ghcr.io/furkan708/mcpify:latest serve ./openapi.json --read-only

...or from source

git clone https://github.com/furkan708/mcpify.git cd mcpify && pip install .

1. preview the tools that will be generated (add --cost for the context price)

mcpify list examples/petstore.json

2. validate the spec is agent-friendly (+ --probe for a live pre-flight)

mcpify doctor examples/petstore.json

3. serve it over MCP

mcpify serve examples/petstore.json --base-url https://petstore.example.com/v1

4. no agent client at hand? try the tools in your terminal

mcpify try examples/petstore.json --base-url https://petstore.example.com/v1

5. or share it over HTTP with the whole team

mcpify serve examples/petstore.json --http 8080 --http-token $SHARED_TOKEN

With authentication

# Bearer token read from the environment (never hardcoded)

export PETSTORE_KEY="sk-..." mcpify serve petstore.json \ --base-url https://petstore.example.com/v1 \ --auth-env PETSTORE_KEY \ --auth-style bearer \ # optional: auto-detected from the spec --read-only

No explicit style needed in the common case — the spec's security declarations pick bearer/basic/header/query (with the right name) for you. For HTTP Basic, the env variable holds username:password: --auth-style basic --auth-env CREDS.

With OAuth2 (client credentials)

For APIs behind an OAuth2 identity provider (RFC 6749 §4.4). Credentials live in the environment; the access token is fetched, cached until its expires_in, refreshed transparently, and re-fetched automatically once if the API answers 401 mid-flight:

export OAUTH2_CLIENT_ID="..."

export OAUTH2_CLIENT_SECRET="..." mcpify serve api.json \ --oauth2-token-url https://idp.example.com/oauth2/token \ --oauth2-client-id-env OAUTH2_CLIENT_ID \ --oauth2-client-secret-env OAUTH2_CLIENT_SECRET \ --oauth2-scope "read write" # optional; --oauth2-client-auth body for token endpoints that reject Basic

Split write identities too: --write-oauth2-token-url (+ client/scope flags) runs a second client-credentials flow for non-GET calls — reads authenticate as the read client, writes as the write client, each with its own token cache and the same 401 self-heal. Mutually exclusive with --write-auth-env (pick one credential kind for writes).

Multiple APIs in one server

Put several OpenAPI documents in one config and serve them as a single tool surface — no gateway, no per-API process:

# .mcpify.toml

[apis.catalog] spec = "https://shop.example.com/openapi.json" auth-env = "CATALOG_TOKEN" # per-API credential cache-ttl = 60 rate-limit = 5 # per-API courtesy throttle (req/s) redact = "password,client_secret" # per-API response masking

[apis.crm] spec = "./crm.yaml" read-only = true # per-API policy base-url = "https://crm.internal/v2" fields = "id,name" # per-API response projection

[apis.weather] spec = "https://api.weather.gov/openapi.json" timeout = 10

Surface switches (--lazy, --enable-preview, --http, --format) are server-wide flags; credentials, policies, caching and retries are per-API.

mcpify list --cost      # preview every API and price each surface

mcpify serve # stdio, all three APIs, prefixed on collisions mcpify serve --http 8080 mcpify try # REPL across every API mcpify status # probes each API concurrently

mcpify status reports per API — [catalog] reachable (status 200, 0.03s) — https://shop.example.com — 31 tools — and exits non-zero if any API is unreachable. When two APIs expose the same tool name (list_pets), both get renamed with their label (catalog_list_pets, crm_list_pets) so nothing silently wins; non-conflicting names stay untouched. The mcpify_health tool returns one report covering every API. Precedence per key: CLI flags > [apis.NAME] > [serve]. Pass a positional spec *or* [apis.*] sections — never both.

Plug it into your agent

Claude Code:

claude mcp add my-api -- mcpify serve openapi.json --read-only

Claude Desktop / Cursor / any MCP client (claude_desktop_config.json):

{

"mcpServers": { "petstore": { "command": "mcpify", "args": ["serve", "~/specs/petstore.json", "--auth-env", "PETSTORE_KEY"] } } }

HTTP transport (team-shared server) — run mcpify serve api.json --http 0.0.0.0:8080 --http-token $TOKEN once, then point HTTP-capable clients at it:

{

"mcpServers": { "petstore": { "type": "http", "url": "http://your-host:8080", "headers": { "Authorization": "Bearer " } } } }

Now ask your agent: *"list the pets, then create one named Milo"* — it discovers list_pets and `create_pe