mcpfabric

Turn an OpenAPI document into a working MCP server.

Most APIs already describe themselves in OpenAPI. MCP clients — Claude Desktop, and the growing set of agent runtimes that speak the protocol — want tools. The gap between the two is mechanical: names have to be legal, parameters have to be merged into one input schema, path placeholders have to be filled and encoded, and errors have to come back as tool results rather than killing the process. This does that, with no dependencies.

pip install -e ".[dev]"
mcpfabric inspect api.json          # see the tools before wiring anything up
mcpfabric serve api.json            # run the MCP server on stdio

Wiring it into a client

Add to the client's MCP configuration:

{
  "mcpServers": {
    "shop": {
      "command": "python3",
      "args": ["-m", "mcpfabric", "serve", "/absolute/path/to/openapi.json"]
    }
  }
}

If the document has no servers block, pass --base-url https://api.example.com. To check the request shapes without touching the network, add --dry-run: every tool call returns the request that would have been sent.

Related MCP server: Contex

What it handles, and why each part matters

Names. MCP requires ^[a-zA-Z0-9_-]{1,64}$. Operation ids containing dots or slashes are sanitised; a missing id falls back to method_path_slug (GET /pets/{id}/toys → get_pets_id_toys). Two operations that sanitise to the same name get _1, _2 suffixes — the compiler counts collisions rather than overwriting a tool.

Input schemas. Path, query, header, and cookie parameters all have to arrive in one object. Path and query parameters keep their own names; query and header parameters are namespaced (query_limit, header_X-Trace) so a path parameter id and a query parameter id can coexist. Path parameters are always required, whatever the document claims, because the URL cannot be built without them.

References. Local $refs are expanded. Cycles are not followed forever: a schema that refers to itself (Node.child -> Node) resolves to a marked placeholder instead of hanging or inventing a depth limit. Remote $refs are rejected rather than fetched — no network call is made while parsing a document you were handed.

Requests. Path values are percent-encoded, so a caller cannot traverse out of the documented route with ../. List query values become repeated keys; booleans render lowercase. A missing required argument, or a path placeholder the document never declared, raises instead of sending a malformed URL.

Failures. An HTTP 4xx/5xx, an unreachable host, or a malformed call comes back as an isError: true tool result. The server keeps running; one bad call does not take down a session.

Protocol

Newline-delimited JSON-RPC 2.0 over stdin/stdout, protocol version 2024-11-05. Supports initialize, tools/list, tools/call, ping, the notifications/* messages, and batches. Malformed JSON produces a -32700 parse error and the stream continues. Logs go to stderr so they cannot corrupt the protocol stream.

Tests

python3 -m pytest -v

70 tests. The suite includes a real http.server fixture and a full initialize → tools/list → tools/call session driven through serve(), so the transport is exercised rather than mocked.

Limits worth knowing

• Local $ref only. Documents that split schemas across files need to be bundled first.

• application/json request bodies only; multipart and form encodings are not built.

• Response schemas are not validated — whatever the API returns is passed through.

• No authentication handling. Put a token into an argument, or front the API with something that adds credentials.

Licence

MIT. Copyright (c) 2026 Konain Sultan Khan.