mcp-openapi-proxy

mcp-openapi-proxy is a Python package implementing a Model Context Protocol (MCP) server that dynamically exposes REST APIs defined by OpenAPI specifications as MCP tools. This allows you to easily integrate any OpenAPI-described API into MCP-based workflows.

Overview

The package supports two operation modes:

Low-Level Mode (Default): Dynamically registers tools for all API endpoints defined in an OpenAPI specification eg. /chat/completions becomes chat_completions().
FastMCP Mode (Simple Mode): Provides a simplified mode for exposing specific pre-configured API endpoints as tools ie. list_functions() and call_functions().

Features

Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI endpoint definitions.
Simple Mode Option: Offers a static configuration option with FastMCP mode.
OpenAPI Specification Support: Works with OpenAPI v3 specifications, and potentially v2.
Flexible Filtering: Supports filtering endpoints by tags, paths, methods, etc. (if implemented)
MCP Integration: Integrates seamlessly with MCP ecosystems to invoke REST APIs as tools.

Installation

MCP Ecosystem Integration

Add mcp-openapi-proxy to your MCP ecosystem by configuring your mcpServers. Generic example:

{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/matthewhand/mcp-openapi-proxy",
                "mcp-openapi-proxy"
            ],
            "env": {
                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
                "API_AUTH_BEARER": "",
                "TOOL_WHITELIST": "",
                "TOOL_NAME_PREFIX": ""
            }
        }
    }
}

For examples of real world APIs like GetZep, Open-Webui, Netlify, Vercel, etc refer to examples.

Modes of Operation

FastMCP Mode (Simple Mode)

Enabled by: Setting OPENAPI_SIMPLE_MODE=true
Description: Exposes a pre-defined set of tools based on specific OpenAPI endpoints defined in code.
Configuration: Requires environment variables for tool definitions.

Low-Level Mode (Default)

Description: Dynamically registers all valid API endpoints from the provided OpenAPI specification as separate tools.
Tool Naming: Tools are named based on normalized OpenAPI path and method.
Behavior: Descriptions are generated from the OpenAPI operation summaries and descriptions.

Environment Variables

OPENAPI_SPEC_URL: URL to the OpenAPI specification JSON file (required).
OPENAPI_LOGFILE_PATH: (Optional) Path for the log file.
OPENAPI_SIMPLE_MODE: (Optional) Set to true for FastMCP mode.
TOOL_WHITELIST: (Optional) A prefix filter to select only certain tools.
TOOL_NAME_PREFIX: (Optional) A string to prepend to all tool names when mapping.

Examples

OpenWebUI Example

1. Confirming the OpenAPI Endpoint

Run the following command to retrieve the OpenAPI specification:

curl http://localhost:3000/openapi.json

If the output is a valid OpenAPI JSON document, it confirms that the endpoint is working correctly.

2. Configuring mcp-openapi-proxy

In your MCP ecosystem configuration file, set the OPENAPI_SPEC_URL to the above endpoint. For example:

{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/matthewhand/mcp-openapi-proxy",
                "mcp-openapi-proxy"
            ],
            "env": {
                "OPENAPI_SPEC_URL": "http://localhost:3000/openapi.json",
                "SERVER_URL_OVERRIDE": "http://localhost:3000/v1",
                "TOOL_WHITELIST": "/models,/chat/completion",
                "API_AUTH_BEARER": "your_openwebui_token_here"
            }
        }
    }
}

OPENAPI_SPEC_URL: The URL to the OpenAPI specification.
SERVER_URL_OVERRIDE: Should the spec not include servers, or you wish to use a different URL.
TOOL_WHITELIST: A comma-separated list of endpoint paths to expose as tools. In this example, only the /api/models and /api/chat/completions endpoints are allowed.
API_AUTH_BEARER: The bearer token for endpoints requiring authentication. Alternatively use ${OPENWEBUI_API_KEY} if configured as an environment variable or stored securely in a .env file.

3. Resulting Tools

With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:

[
    {
        "name": "api_models",
        "description": "Fetches available models from /api/models"
    },
    {
        "name": "api_chat_completions",
        "description": "Generates chat completions via /api/chat/completions"
    }
]

4. Visual Verification

You can verify the registration of these tools by inspecting the MCP server logs or using your MCP client.

Fly.io Example

1. Verify the OpenAPI Endpoint

Run the following command to retrieve the Fly.io OpenAPI JSON specification:

curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json

Ensure the response is a valid OpenAPI JSON document containing an "openapi" field (e.g., "openapi": "3.0.0") and defined API paths.

2. Configure mcp-openapi-proxy for Fly.io

Update your MCP ecosystem configuration to point to the Fly.io endpoint. For example:

{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": [
                "--from",
                "git+https://github.com/matthewhand/mcp-openapi-proxy",
                "mcp-openapi-proxy"
            ],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
                "SERVER_URL_OVERRIDE": "https://api.machines.dev",
                "TOOL_WHITELIST": "/machines/list,/machines/start,/machines/status",
                "API_AUTH_BEARER": "${FLY_API_TOKEN}"
            }
        }
    }
}

3. Resulting Tools

With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:

[
    {
        "name": "machines_list",
        "description": "Fetches machine listing from /machines/list"
    },
    {
        "name": "machines_start",
        "description": "Initiates machine start via /machines/start"
    },
    {
        "name": "machines_status",
        "description": "Retrieves machine status from /machines/status"
    }
]

Troubleshooting

Missing OPENAPI_SPEC_URL: Verify that the OPENAPI_SPEC_URL environment variable is set and points to a valid OpenAPI JSON file.
Invalid OpenAPI Spec: Ensure the JSON specification complies with the OpenAPI standard.
Filtering Issues: Check that TOOL_WHITELIST is correctly defined to filter the desired classes.
Logging: Consult the logs (as defined by MCP_OPENAPI_LOGFILE_PATH) for debugging information.
Verify uvx Run the server directly from the GitHub repository using uvx:

uvx --from git+https://github.com/matthewhand/mcp-openapi-proxy mcp-openapi-proxy

License

This project is licensed under the MIT License. See the LICENSE file for details.

Metadata

Release files for mcp-openapi-proxy 0.1.1741342058

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-openapi-proxy 0.1.1741342058
File	Size	Uploaded	Provenance
mcp_openapi_proxy-0.1.1741342058.tar.gz	14.6 kB	Mar 7, 2025	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for mcp-openapi-proxy 0.1.1741342058
File	Interpreter	ABI	Platform	Reset
mcp_openapi_proxy-0.1.1741342058-py3-none-any.whl 15.0 kB Mar 7, 2025 Without provenance	Python 3	none	any	Details

Total release size: 29.7 kB

Release files / mcp_openapi_proxy-0.1.1741342058.tar.gz

Download URL	mcp_openapi_proxy-0.1.1741342058.tar.gz
Size	14.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`c1f325e0c7dc7f13aab57ef9e49050a591ec540796bd1a64511e0a9d23d16fce`
BLAKE2b-256 checksum How to use checksums	`c7fc350d4c4cf4a37c2983138c634455caf8408622ddccfd2dc4d901abcef029`
Upload date	Mar 7, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Release files / mcp_openapi_proxy-0.1.1741342058-py3-none-any.whl

Download URL	mcp_openapi_proxy-0.1.1741342058-py3-none-any.whl
Size	15.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7c377d82fa5037e2cb3f7eb30ac5e4791e08a5b4947dffe33877d4552293ca82`
BLAKE2b-256 checksum How to use checksums	`8dd2a5beaf5c9802440fe03a14959bad74569dffa0b41f65abe16ecf9ec7e5af`
Upload date	Mar 7, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.12.9`

Security for mcp-openapi-proxy 0.1.1741342058

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.