Turning one API operation into one MCP tool is already commodity. The harder and more useful problem is deciding which tools should exist, what they should be called, what they should accept and return, and what may not be invoked without a human in the loop.

This compiler answers that with provenance on every field, a safety gate that refuses to emit what it cannot justify, and governance derived separately from code.

specification -> ingestion -> API Semantic IR -> planner -> tool plan
                                                    |
                              overlay (human decisions)
                                                    |
                                              policy manifest
                                                    |
                                          generated tool surface
                                                    |
                                    runnable MCP server (HTTP or SOAP)

Contents

• What it does
• What is not demonstrated
• Install
• Try it
• How it works
• Design properties
• Reproducibility
• Documentation
• Scope
• Author
• Licence

What it does

Ingests OpenAPI 3.x, Swagger 2.0 and WSDL 1.1, normalizes them into one provider-independent intermediate representation, plans a tool surface, derives a policy manifest, and emits a runnable MCP server for the approved part: over HTTP for OpenAPI, over SOAP envelopes for WSDL. The compiler itself binds to no MCP SDK, never calls a model, and never reaches the network.

This has been exercised on specifications and services written by other people, which is where the interesting defects live:

The governance is the part worth having. Every field carries provenance, judgement is proposed rather than applied, write and destructive tools are not emitted in executable form until a human approves them by class, and what the compiler cannot demonstrate it records as unresolved instead of assuming.

What is not demonstrated

The design thesis, that a semantically planned surface beats one tool per operation on task success, unsafe-action rate and cost, has been measured four times and is still unanswered.

Every comparison was pre-registered: the hypothesis, corpus, arms, model, success definition and significance threshold were fixed in a digested document before the run, and each run records that digest. All returned inconclusive, and the nominal direction reversed between them. Nothing here should be read as evidence that the semantic surface performs better. It is an argued position that has so far survived no test capable of confirming it.

The most distinctive claim, that operations should be composed into workflow tools, is untested rather than unsupported. The rule that proposes composites fires nowhere on the first benchmark API, and designing a better one after reading that benchmark's solution paths would fit the treatment to the test set. It needs a benchmark whose tasks have not been read here.

What the runs did establish is mostly about the instrument, and it was worth the tokens. Several defects were found only by pointing the system at a specification and a task set written by other people: a parser that marked every optional argument required, generated schemas no client would load, a store in which a read mutated state and a bulk delete removed everything, and oracles that scored the route an annotator took rather than the outcome a goal asked for. Each is fixed, and the rules that would have prevented the last class now fail the build.

Install

pip install api-mcp-compiler

Install from source, and verify

python -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/python scripts/verify_repo.py

The gate runs pytest, ruff, mypy in strict mode, validates every committed example against its versioned JSON Schema, builds the wheel and sdist and proves an installed copy can validate its own artifacts, and re-executes the notebook to confirm its stored outputs still match. Lint and type-checker versions are pinned exactly, so the gate means the same thing on every machine.

Try it

# Normalize a specification into the intermediate representation
.venv/bin/python -m api_mcp_compiler.cli inspect examples/openapi/order_service.yaml

# Plan a tool surface, and read the review report a human would approve from
.venv/bin/python -m api_mcp_compiler.cli review examples/openapi/order_service.yaml

# Derive the governance manifest
.venv/bin/python -m api_mcp_compiler.cli policy examples/openapi/inventory_service.yaml

# Generate the surface, applying decisions a reviewer already recorded
.venv/bin/python -m api_mcp_compiler.cli generate examples/openapi/order_service.yaml \
  --overlay examples/overlays/order_service.overlay.json

# Write the conversion report a reviewer reads. Never overwrites an earlier one.
.venv/bin/python -m api_mcp_compiler.cli report examples/openapi/order_service.yaml

# Approve by class, so nobody hand-edits an overlay
.venv/bin/python -m api_mcp_compiler.cli approve examples/openapi/order_service.yaml \
  --overlay build/order.overlay.json --risk read

# Emit a runnable MCP server for the approved part of the surface
.venv/bin/python -m api_mcp_compiler.cli serve examples/openapi/order_service.yaml \
  --overlay examples/overlays/order_service.overlay.json --out build/order_server.py

# The same for SOAP. A WSDL operation needs its side effect recorded by a reviewer first,
# because WSDL carries no signal to infer one from.
.venv/bin/python -m api_mcp_compiler.cli serve examples/wsdl/customer_service.wsdl \
  --overlay examples/overlays/customer_service.overlay.json --out build/customer_server.py

# Score a surface against a task corpus, using deterministic oracles over final state
.venv/bin/python -m api_mcp_compiler.cli evaluate examples/openapi/order_service.yaml \
  examples/evals/order_tasks.json

# Fetch and pin the remote references a specification names. The only command that
# reaches the network, so that compiling never has to.
.venv/bin/python -m api_mcp_compiler.cli vendor-refs SPEC --lock refs.lock.json --record

# Check every artifact against its schema and list what is unresolved
.venv/bin/python -m api_mcp_compiler.cli validate examples/openapi/inventory_service.yaml

To read the same walk with every intermediate value printed, the provenance on a field, the rationale behind a rename, the scope chosen over the union of its alternatives, the gate holding a destructive tool and the review decision that releases it, open notebooks/from_specification_to_server.ipynb. Its stored outputs are re-executed and compared by the verification gate, so they cannot drift from the code that produced them.

How it works

Ingestion, planning, policy synthesis and code generation are separate stages with separate contracts. Each contract is versioned independently and pinned, so a document written against one version fails validation loudly instead of being misread.

Design properties

Every informative field carries provenance. A record names the field, a pointer into the source document, how the value was derived (source, normalized, inferred, default) and a confidence. An inference cannot claim certainty and a source fact cannot express doubt; the contract rejects both.

Nothing is dropped silently. Constructs that cannot be resolved become Ambiguity records, and a completeness sweep reports every key an adapter did not consume. Duplicate mapping keys are refused outright in YAML and JSON, because a dropped key never reaches the parser to be swept.

Ingestion never reaches the network. $ref resolution defaults to deny. External files load only from directories you name with --allow-dir, checked against real paths so ../ cannot escape. A specification is third-party input, and following its pointers is an action taken on its author's behalf.

A document that splits its schemas across URLs still compiles, because fetching is a separate command rather than a flag on ingestion. vendor-refs fetches each remote document once, pins it by digest and writes a lock; a compile then reads the pinned files, verifies them, and refuses anything the lock does not name. An upstream edit surfaces as a mismatch rather than as a surface that quietly became something else.

Accepted is not done. An operation answering 202 has been accepted, not performed. The surface says so, and names the header to poll where the document declares one, because an agent told nothing reports a goal met before the work has started.

Inference can only make an operation look less safe, never more. Destructive wording raises a write to destructive; it never lowers a class, and a read described destructively is flagged for review rather than quietly reclassified. SOAP operations are never classified by inference at all, because WSDL carries no signal equivalent to an HTTP method.

Judgement never becomes silent action. The planner proposes renames, omissions, groupings, output projections and composite workflows, each with a rationale and a confidence. Nothing it proposes changes the surface until a reviewer records the decision in an overlay, and an overlay is bound by digest to the specification revision it was reviewed against.

A tool is executable only if it earned it. Reads pass automatically once validated. Write, destructive and privileged tools stay disabled until approved. A blocking ambiguity, an unclassified risk, or policy that could not be derived keeps a tool disabled regardless of approval. Refused tools are still emitted carrying the reason, so the surface never shrinks quietly.

Governance is derived, not assumed, and then obeyed. Policy is generated separately from code: least-privilege scopes chosen from the security alternatives rather than their union, approval and confirmation classes, retry rules from inferred idempotency, call budgets, output ceilings, redaction and audit rules.

The generated server acts on all of it. A confirmation token is bound to a digest of the exact arguments, expires, and is single use. Each credential is placed where the specification said it goes, read from the environment at call time and never written into a file. Retries are bounded by the derived policy and never repeat a call that may already have taken effect. Call budgets are counted and a call over them is refused with the limit and when it lifts, rather than queued.

An earlier version derived every one of those and acted on none of them, which is the failure this property is worded to exclude.

Evaluation is decided by state, never by a model, and says where it is guessing. A task names source operations rather than tool names, so one corpus scores both planners. A run records which operations an agent reached for and how many of its calls the task permitted, measured against the permitted set and never against a recorded solution. The mock service that decides final state names the rule behind every effect and how much it is worth: on a real 40-operation API, 35 are modelled at high confidence and 5 are not, and a script reports which. Success is judged by the state the service ends in, together with oracles for absence of mutation, prohibited operations and confirmation adherence. No safety or success number depends on a judge, and latency and token cost are recorded as null rather than estimated, because a fabricated number sitting beside measured ones is indistinguishable from a measured one.

What the compiler cannot enforce, it says so. Server-side authorization and protection against confused-deputy designs are properties of a deployed service, not of a generated artifact. The manifest records them as requirements and never reports them as satisfied.

Reproducibility

Every document loaded during a compile is digested, not only the root, so an artifact stays tied to the exact bytes it came from. Golden IR, plan, policy, surface and review artifacts are committed. Regenerate them deliberately and review the diff:

.venv/bin/python scripts/regen_golden.py

Documentation

The full guide lives at api-mcp.subhadipmitra.com: concepts, a command reference, the contract schemas, the SOAP path, and how evaluation and pre-registration work. Its source is in guide/.

Your OpenAPI Spec Is Not an Agent Interface is the write-up: why transliterating a specification into tools is the easy half of the problem, what the compiler does about the other half, and what four pre-registered comparisons did and did not establish.

Scope

Uses synthetic and public specifications only. No credentials, customer specifications or proprietary schemas belong in this repository.

Author

Subhadip Mitra subhadipmitra.com · contact@subhadipmitra.com

If you use this in academic work, please cite it. CITATION.cff has the metadata, and GitHub renders it as a citation block on the repository page.

Licence

Apache-2.0. See LICENSE and NOTICE.

Apache rather than a copyleft licence, deliberately. The interesting part of this project is what it decides a good tool surface looks like and what it refuses to emit; restricting who may build on that would cost adoption without protecting anything worth protecting. The patent grant also matters for the enterprises most likely to have a specification estate that needs converting.

Benchmark specifications and services used to test the compiler are fetched at the point of use and never redistributed here, so this repository carries no third-party source. Their licences and attributions are recorded in examples/benchmarks/manifest.json.

Servers this compiler generates are its output, not a derivative of it. They carry whatever licence their author chooses.