mcp-scribe

MCP Scribe

Transcribe any OpenAPI schema into a production-grade MCP server.

---

Overview

Point MCP Scribe at an OpenAPI schema. Get an MCP server.

Every operation in the spec becomes a tool a model can call, with the JSON Schema, the credentials, the retries, the rate limiting, and the response shaping already handled. There is no generated code to maintain and no adapter layer to keep in sync — the spec is the source of truth, and the server is derived from it at startup.

MCP Scribe is designed for teams putting real APIs in front of language models, where the failure modes that matter are credential leakage, runaway retries against a billable endpoint, and tool surfaces too large for a model to navigate.

---

Installation

pip install mcp-scribe

From source, as a global CLI:

git clone https://github.com/kyegomez/mcp-scribe && cd mcp-scribe
uv tool install --editable ".[http]"

The http extra installs uvicorn and starlette, required only for HTTP transport. A stdio server needs neither.

Requirements: Python 3.10 – 3.13.

---

Quick start

Deploy a shared server

One command. Spec in, server up.

mcp-scribe deploy https://api.swarms.world/openapi.json --port 8000

Call that Server

import asyncio
import os
import sys

from dotenv import load_dotenv
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.shared._httpx_utils import create_mcp_http_client

load_dotenv()

# Streamable HTTP path defaults to /mcp (see transport.path).
MCP_URL = "http://127.0.0.1:8000/mcp"


async def main() -> None:
    api_key = os.environ.get("SWARMS_API_KEY")
    if not api_key:
        sys.exit(
            "set SWARMS_API_KEY first: export SWARMS_API_KEY=sk-..."
        )

    http = create_mcp_http_client(headers={"x-api-key": api_key})
    async with http, streamable_http_client(
        MCP_URL, http_client=http
    ) as (read, write), ClientSession(read, write) as session:
        await session.initialize()
        result = await session.call_tool(
            "get_available_models_v1_models_available_get",
            {},
        )
        print(result.content[0].text)


if __name__ == "__main__":
    asyncio.run(main())

CLI Commands

Usage: mcp-scribe [OPTIONS] COMMAND [ARGS]...

Turn any OpenAPI schema URL into a production-grade MCP server.

Options:
  --help          Show this message and exit.

Commands:
  serve     Run the MCP server.
  deploy    Serve over HTTP with production defaults. The short path to a shared server.
  inspect   Show the tools a spec produces — the fastest way to validate a setup.
  call      Invoke one tool from the terminal — the same code path the server uses.
  generate  Write a self-contained, deployable MCP server project for a spec.
  install   Build the server and register it with your MCP client in one step.
  version   Print the version.

Key capabilities

| Capability | What it delivers | | --- | --- | | Universal spec ingestion | OpenAPI 3.1, 3.0, and Swagger 2.0 from a URL, file, or stdin — JSON or YAML. Swagger 2.0 is converted up front; external and recursive $refs are prefetched and resolved. | | Zero-code tool generation | One MCP tool per operation, emitted as JSON Schema 2020-12 with the full style/explode matrix, $defs for recursive models, and automatic body flattening for tool-calling accuracy. | | Credential isolation | Credential parameters declared in the spec are stripped from tool schemas and injected at request time. The model is never asked to produce a secret it does not hold. | | Enterprise authentication | API key (header, query, cookie), bearer, HTTP basic, OAuth2 client credentials with automatic refresh, and arbitrary static headers — composable, all applied per request. | | Multi-tenant isolation | Per-caller credential passthrough with header allowlisting and fail-closed enforcement, so one shared server does not mean one shared identity or one shared bill. | | Resilience by default | Full-jitter exponential backoff honoring Retry-After, a per-host circuit breaker, a token bucket, a concurrency ceiling, and a wall-clock budget per tool call. | | Safe-by-default retries | POST and PATCH are never retried unless explicitly enabled. Re-sending a billable request is treated as worse than failing. | | Attack-surface control | Filter by tag, path regex, method, or operationId; --read-only restricts a server to GET/HEAD/OPTIONS in one flag. | | Context governance | Responses are truncated to a configurable budget with a hint telling the model how to narrow the request. | | Dual transport | stdio for personal, per-user servers; streamable HTTP with a /health probe and stateless sessions for shared, horizontally scaled deployments. | | Secret hygiene | .env files, MCP_SCRIBE_* environment variables, and ${VAR} interpolation in config. Secrets are SecretStr in memory and redacted in output. | | Operational tooling | inspect to validate a setup without starting anything, call --dry-run to see the exact outgoing request, structured JSON logging, and hot spec reload. | | Deployable artifacts | generate emits a self-contained project with a Dockerfile, pinned requirements, config, and a vendored spec for offline startup. |

---

Documentation

| Document | Contents | | --- | --- | | docs/DOCS.md | Complete user guide — mental model, transports, credentials, multi-tenancy, filtering, schema shaping, reliability, debugging, deployment, and troubleshooting. | | docs/REFERENCE.md | Exhaustive reference — every CLI command and flag, every configuration key with types and defaults, the full environment-variable table, the Python API, and the exception hierarchy. | | CLAUDE.md | Contributor and agent guide — commands, module-by-module architecture, load-bearing invariants, conventions, and gotchas. | | MCP_SCRIBE_SKILL.md | Agent skill definition — how an autonomous agent should choose commands, validate setups, and handle credentials. |

---

License

Apache-2.0. See LICENSE.

---

Citation

@misc{mcpscribe2026,
    title   = {mcp-scribe: production-grade MCP servers from OpenAPI schemas},
    author  = {Gomez, Kye},
    year    = {2026},
    url     = {https://github.com/kyegomez/mcp-scribe}
}

@misc{mcp2024,
    title   = {Model Context Protocol},
    author  = {Anthropic},
    year    = {2024},
    url     = {https://modelcontextprotocol.io}
}