openapi-to-mcp
README.md
## MCP Scribe
**Transcribe any OpenAPI schema into a production-grade MCP server.**
[](https://pypi.org/project/mcp-scribe/)
[](https://pypi.org/project/mcp-scribe/)
[](LICENSE)
[](https://github.com/kyegomez/swarms)
[](https://swarms.ai)
[](https://discord.gg/SSj7FyRSwy)
[](https://twitter.com/swarms_corp)
---
## 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
```bash
pip install mcp-scribe
```
From source, as a global CLI:
```bash
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.
```bash
mcp-scribe deploy https://api.swarms.world/openapi.json --port 8000
```
### Call that Server
```python
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 `$ref`s 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](docs/DOCS.md)** | Complete user guide — mental model, transports, credentials, multi-tenancy, filtering, schema shaping, reliability, debugging, deployment, and troubleshooting. |
| **[docs/REFERENCE.md](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](CLAUDE.md)** | Contributor and agent guide — commands, module-by-module architecture, load-bearing invariants, conventions, and gotchas. |
| **[MCP_SCRIBE_SKILL.md](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](LICENSE).
---
## Citation
```bibtex
@misc{mcpscribe2026,
title = {mcp-scribe: production-grade MCP servers from OpenAPI schemas},
author = {Gomez, Kye},
year = {2026},
url = {https://github.com/kyegomez/mcp-scribe}
}
```
```bibtex
@misc{mcp2024,
title = {Model Context Protocol},
author = {Anthropic},
year = {2024},
url = {https://modelcontextprotocol.io}
}
```
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessUnresponsive