prompt-to-mcp

Describe the MCP server you want. Point at an OpenAPI spec. Get a small, curated FastMCP server as editable code.

pip install prompt-to-mcp        # or run it without installing: uvx prompt-to-mcp

Big APIs make bad MCP servers when converted one tool per endpoint: Stripe's spec becomes 587 tools and ~463,000 tokens of definitions, more than 14 times a 32k context window. prompt-to-mcp compiles the server you describe instead, with just the tools that serve your use case, and ships an eval harness that measures the result.

Contents

• Quick start
• Example: 587 Stripe operations, 6 tools
• How it works
• Use the generated server
• Models and providers
• Evidence
• Coverage tradeoff
• CLI reference
• Development
• License

Quick start

You need Python 3.12+ and one LLM. A local Ollama model works; so does any key that speaks the Anthropic or OpenAI protocol. Nothing to clone.

# grab a small example spec
curl -o petstore.yaml https://raw.githubusercontent.com/KnaniOussama/prompt-to-mcp/master/tests/fixtures/petstore.yaml

# 1. see what a naive 1:1 conversion would cost (free, no LLM involved)
uvx prompt-to-mcp inspect petstore.yaml

# 2. describe the server you want (the one step that calls an LLM)
uvx prompt-to-mcp plan petstore.yaml "a server for looking up pets and their orders" \
    -o pets.toolplan.yaml --provider ollama --model qwen2.5:7b

# 3. compile it into a runnable server (free, deterministic)
uvx prompt-to-mcp build pets.toolplan.yaml --spec petstore.yaml -o pets-server/

Step 2 writes pets.toolplan.yaml, a plain YAML plan of the tools. Open it, edit anything you disagree with, and rerun step 3. Rebuilding is free; only plan and eval call a model. p2m is a short alias for the same CLI.

Prefer automatic curation of the whole API instead of a description? Pass --auto in step 2.

Example: 587 Stripe operations, 6 tools

One sentence turned the full Stripe spec into a server scoped to a single job:

prompt-to-mcp plan stripe-spec.json \
    "a server for support agents to manage customers, invoices and refunds" \
    -o stripe-support.toolplan.yaml --max-tools 8

The description drove the curation. The model kept the customer, invoice, and refund surface and left the rest of the API (subscriptions, products, connect, webhooks, reporting) out:

Six tools, ~956 tokens of definitions, from an API whose naive conversion needs ~463,000. The committed artifacts: stripe-support.toolplan.yaml and generated/stripe-support/.

The same spec with --auto and no description produces a broader 11-tool general server (stripe.toolplan.yaml). Same machinery, two shapes: one fits your task, one fits the API.

How it works

flowchart LR
    S["OpenAPI spec"] --> I["inspect<br/><i>damage report</i>"]
    I --> P["plan<br/><i>1 LLM pass</i>"]
    P --> Y[["ToolPlan YAML<br/>editable, diff-friendly"]]
    Y --> B["build<br/><i>deterministic codegen</i>"]
    B --> M["FastMCP server"]
    M --> E["eval<br/><i>measure it</i>"]
    style Y fill:#fde68a,stroke:#b45309,color:#000
    style P fill:#bfdbfe,stroke:#1e40af,color:#000

The ToolPlan YAML is the load-bearing design decision. The model proposes; you review and edit plain YAML; build compiles it with no model in the loop. Nothing the LLM produces is a black box. A tool in the plan looks like this:

- name: refund_lookup
  intent: List or retrieve refunds
  read_only: true
  endpoints: [GET /v1/refunds, GET /v1/refunds/{refund}]
  dispatch: { mode: select, selector: mode }   # "list" or "get" picks the endpoint
  response_filter:
    fields: [id, amount, currency, status, reason, created, charge]

Generated servers filter API responses to the fields the agent needs, inject auth from an environment variable at runtime (never baked into code), and turn API errors into plain messages an agent can act on.

Use the generated server

Each generated package is self-contained (needs only fastmcp and httpx) and comes with its own README naming its auth variable.

cd pets-server
PETSTORE_API_KEY=... fastmcp run server.py

Claude Code:

claude mcp add pets -e PETSTORE_API_KEY=... -- uv run --with fastmcp fastmcp run /path/to/pets-server/server.py

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "pets": {
      "command": "uv",
      "args": ["run", "--with", "fastmcp", "fastmcp", "run", "/path/to/pets-server/server.py"],
      "env": { "PETSTORE_API_KEY": "..." }
    }
  }
}

Models and providers

The LLM layer speaks both wire protocols, so any model works: hosted or local. This repo's own artifacts were made with a hosted model for curation and a local 7B for the evals, with zero code changes between them.

Anything else: --base-url <url> --api-protocol openai|anthropic. Configuration resolves flags first, then environment variables (P2M_API_KEY, P2M_MODEL, P2M_BASE_URL, P2M_API_PROTOCOL, P2M_MAX_OUTPUT_TOKENS; bare ANTHROPIC_API_KEY or OPENAI_API_KEY work as key fallbacks), then a .env in the working directory, then preset defaults. prompt-to-mcp providers prints the full picture.

Two provider quirks are handled for you: Gemini 3 requires its per-call thought_signature echoed back on multi-turn tool use, and some gateways count hidden reasoning tokens against max_tokens (the output budget is configurable, with a truncation-aware retry).

Evidence

Every request an agent makes carries the full tool list. Drawn to scale against a 32k-token window, for GitHub's API:

naive      1,206 tools │ ████████████████████████████████████████  414,263 tok   12.6× over ✗
32k window   (ceiling) │ ███                                         32,768 tok
distilled      9 tools │ ▏                                            1,758 tok   18.6× under ✓

A naive tool list this size cannot fit before the agent reads a word of the task. Strict providers reject it; lenient ones (Ollama) silently truncate it. The eval harness records the former as provider_error and refuses the latter up front with a pre-flight --model-context guard, so a mangled run is never reported as a real one.

The benchmarks below used --auto (no description), which makes them a fair, description-free comparison: naive one-tool-per-endpoint versus automatic curation, same agent (qwen2.5:7b, local), same scenarios, live APIs.

The naive side was refused by the context guard in every trial; it does not fit a 32k model. Full artifacts: eval_runs/headline/ and eval_runs/stripe/.

xychart-beta
    title "Curated GitHub server: trials passed per scenario (3 trials each)"
    x-axis ["repo-overview", "repo-metadata", "list-branches", "repo-language", "search-repo"]
    y-axis "trials passed" 0 --> 3
    bar [3, 3, 3, 3, 1]

The weak scenario is also the expensive one: search-repo passed 1 of 3 and consumed about 2.7 times the input tokens of any other task. A small model that cannot decide between similar options flails, and flailing costs tokens:

xychart-beta
    title "Mean input tokens per task, by scenario"
    x-axis ["repo-overview", "repo-metadata", "list-branches", "repo-language", "search-repo"]
    y-axis "input tokens" 0 --> 10000
    bar [3582, 4062, 3448, 3401, 9569]

What this shows: the context problem is decisive, and the pipeline works end to end on live APIs with a small local agent. What it does not show yet: a comparison against a naive server that fits (cap it with --naive-max-tools on a large-context model), or a no-tools control. Both are supported by the harness and are the next experiments worth running.

Known limits:

Coverage tradeoff

Curation drops long-tail endpoints on purpose. The Stripe support server above cannot touch subscriptions or payouts, because the description did not ask for them. That is the point: you decide what is covered, and the tool surface stays small enough to fit and cheap enough to reason over.

Nothing is locked in. A missing capability is one YAML edit and a free rebuild away: add the endpoint to a tool (or add a tool) in the ToolPlan, run build, done.

CLI reference

Provider selection flags (--provider, --model, --base-url, --api-protocol, --max-output-tokens) work on plan and eval alike. On Windows, set PYTHONUTF8=1 for live runs.

Development

git clone https://github.com/KnaniOussama/prompt-to-mcp && cd prompt-to-mcp
uv sync
uv run pytest    # offline, no keys needed

See CONTRIBUTING.md for ground rules (determinism of build is enforced by tests) and SECURITY.md for what to know before running against real accounts. The design document is DESIGN.md.

License

MIT. See LICENSE.