mcpify

English | Türkçe

Turn any OpenAPI REST API into an MCP 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