mcp4api

mcp4api turns your API docs into a working MCP server, then calls every generated tool against your API and reports which ones work. Built for platform teams who want their product callable by agents.

Recording

Install

pip install mcp4api
uvx mcp4api

Quickstart

These commands need no API key. They reuse the committed manifest and cassettes, regenerate the other artifacts in place, and exit 3. The sample's one known gap is get_book: page_count is a string in the API and an integer in the spec.

git clone https://github.com/smusali/mcp4api && cd mcp4api
uvx mcp4api examples/sample-api/openapi.yaml --offline --out examples/sample-api
cat examples/sample-api/report/verification.md

Generated tool

upload_book_file from the Shelf sample is four calls composed into one tool.

@mcp.tool(
    title="Upload Book File",
    annotations=ToolAnnotations(
        read_only_hint=False,
        destructive_hint=False,
        idempotent_hint=False,
        open_world_hint=True,
    ),
)
async def upload_book_file(
    book_id: Annotated[str, Field(description="book id")],
    content_type: Annotated[str, Field(description="content type")],
    data: Annotated[str, Field(description="data")],
    filename: Annotated[str, Field(description="filename")],
) -> UploadBookFileResult:
    """Upload a file and attach it to a book."""
    create_upload = await api.request(
        "POST",
        "/uploads",
        body={"content_type": content_type, "filename": filename},
        auth=(("api_key", "header", "X-API-Key"),),
    )
    _upload_part = await api.request(
        "PUT",
        "/uploads/{upload_id}/parts/{part_number}",
        path_params={
            "part_number": UPLOAD_BOOK_FILE_PART_NUMBER,
            "upload_id": api.pick(create_upload, "id"),
        },
        body={"data": data},
        auth=(("api_key", "header", "X-API-Key"),),
    )
    _complete_upload = await api.request(
        "POST",
        "/uploads/{upload_id}/complete",
        path_params={"upload_id": api.pick(create_upload, "id")},
        auth=(("api_key", "header", "X-API-Key"),),
    )
    attach_book_file = await api.request(
        "PUT",
        "/books/{book_id}/file",
        path_params={"book_id": book_id},
        body={"upload_id": api.pick(create_upload, "id")},
        auth=(("api_key", "header", "X-API-Key"),),
    )

    return UploadBookFileResult.model_validate(attach_book_file)

Verification report

CI

mcp/ holds the committed tools.yaml and cassettes. Exit 3 fails the job.

- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
  with:
    persist-credentials: false
- uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e  # v10.3.2
- run: uvx mcp4api openapi.yaml --offline --out mcp/

Limitations

• OpenAPI 3.0, 3.1, 3.2, and Swagger 2.0 only.
• API key or bearer token authentication only.
• A failing tool is a known gap. It is not repaired.
• Agent curation needs an Anthropic API key.

The full list is in Limitations.

Contributing

See Contributing.

License

MIT