mcp-openapi-proxy

mcp-openapi-proxy is a Python package that implements a Model Context Protocol (MCP) server, designed to dynamically expose REST APIs—defined by OpenAPI specifications—as MCP tools. This facilitates seamless integration of OpenAPI-described APIs into MCP-based workflows.

Overview
Features
Installation
- MCP Ecosystem Integration
Modes of Operation
- FastMCP Mode (Simple Mode)
- Low-Level Mode (Default)
Environment Variables
Examples
Troubleshooting
License

Overview

The package offers two operational modes:

Low-Level Mode (Default): Dynamically registers tools corresponding to all API endpoints specified in an OpenAPI document (e.g., /chat/completions becomes chat_completions()).
FastMCP Mode (Simple Mode): Provides a streamlined approach, exposing a predefined set of tools (e.g., list_functions() and call_function()) based on static configurations.

Features

Dynamic Tool Generation: Automatically creates MCP tools from OpenAPI endpoint definitions.
Simple Mode Option: Offers a static configuration alternative via FastMCP mode.
OpenAPI Specification Support: Compatible with OpenAPI v3, with potential support for v2.
Flexible Filtering: Allows endpoint filtering through whitelisting by paths or other criteria.
Payload Authentication: Supports custom authentication via JMESPath expressions (e.g., for APIs like Slack that expect tokens in the payload, not the HTTP header).
Header Authentication: Uses Bearer by default for API_KEY in the Authorization header, customizable for APIs like Fly.io requiring Api-Key.
MCP Integration: Seamlessly integrates with MCP ecosystems for invoking REST APIs as tools.

Installation

Install the package directly from PyPI using the following command:

uvx mcp-openapi-proxy

MCP Ecosystem Integration

To incorporate mcp-openapi-proxy into your MCP ecosystem, configure it within your mcpServers settings. Below is a generic example:

{
    "mcpServers": {
        "mcp-openapi-proxy": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
                "API_KEY": "",
                "TOOL_WHITELIST": "",
                "TOOL_NAME_PREFIX": "",
                "API_KEY_JMESPATH": "",
                "API_AUTH_TYPE": ""
            }
        }
    }
}

Refer to the Examples section below for practical configurations tailored to specific APIs.

Modes of Operation

FastMCP Mode (Simple Mode)

Enabled by: Setting the environment variable OPENAPI_SIMPLE_MODE=true.
Description: Exposes a fixed set of tools derived from specific OpenAPI endpoints, as defined in the code.
Configuration: Relies on environment variables to specify tool behavior.

Low-Level Mode (Default)

Description: Automatically registers all valid API endpoints from the provided OpenAPI specification as individual tools.
Tool Naming: Derives tool names from normalized OpenAPI paths and methods.
Behavior: Generates tool descriptions from OpenAPI operation summaries and descriptions.

Environment Variables

OPENAPI_SPEC_URL: (Required) The URL to the OpenAPI specification JSON file (e.g., https://example.com/spec.json or file:///path/to/local/spec.json).
OPENAPI_LOGFILE_PATH: (Optional) Specifies the log file path.
OPENAPI_SIMPLE_MODE: (Optional) Set to true to enable FastMCP mode.
TOOL_WHITELIST: (Optional) A comma-separated list of endpoint paths to expose as tools.
TOOL_NAME_PREFIX: (Optional) A prefix to prepend to all tool names.
API_KEY: (Optional) Authentication token for the API, sent as Bearer <API_KEY> in the Authorization header by default.
API_KEY_JMESPATH: (Optional) JMESPath expression to map API_KEY into request parameters (e.g., query.token for Slack).
API_AUTH_TYPE: (Optional) Overrides the default Bearer Authorization header type (e.g., Api-Key for Fly.io).

Examples

This section provides examples to demonstrate configuration simplicity, authentication flexibility, and detailed tool generation.

Fly.io Example

Fly.io provides a simple API for managing machines, making it an ideal starting point. Obtain an API token from Fly.io documentation.

1. Verify the OpenAPI Specification

Retrieve the Fly.io OpenAPI 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.

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

Update your MCP ecosystem configuration:

{
    "mcpServers": {
        "flyio": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
                "API_KEY": "<your_flyio_token_here>",
                "API_AUTH_TYPE": "Api-Key"
            }
        }
    }
}

OPENAPI_SPEC_URL: Points to the Fly.io OpenAPI specification.
API_KEY: Your Fly.io API token (replace <your_flyio_token_here>). Find it in ~/.fly/config.yml under access_token.
API_AUTH_TYPE: Set to Api-Key for Fly.io’s header-based authentication (overrides default Bearer).

3. Resulting Tools

This generates tools like:

get_machines (lists machines).
post_machines (creates machines).

Run list_functions in FastMCP mode to see the full set.

4. Testing

Verify with:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json" API_KEY="<your_flyio_token_here>" API_AUTH_TYPE="Api-Key" uvx mcp-openapi-proxy

Slack Example

Slack’s API showcases payload-based authentication with JMESPath. Obtain a bot token from Slack API documentation.

1. Verify the OpenAPI Specification

Retrieve the Slack OpenAPI specification:

curl https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json

Ensure it’s a valid OpenAPI JSON document.

2. Configure mcp-openapi-proxy for Slack

Update your configuration:

{
    "mcpServers": {
        "slack": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json",
                "TOOL_WHITELIST": "/chat,/bots,/conversations,/reminders,/files,/users",
                "API_KEY": "<your_slack_bot_token>",
                "API_KEY_JMESPATH": "token",
                "TOOL_NAME_PREFIX": "slack_"
            }
        }
    }
}

OPENAPI_SPEC_URL: Slack’s OpenAPI spec URL.
TOOL_WHITELIST: Limits tools to useful endpoint groups (e.g., chat, conversations, users).
API_KEY: Your Slack bot token (e.g., xoxb-...—replace <your_slack_bot_token>).
API_KEY_JMESPATH: Maps API_KEY to the token field in the request payload, per Slack’s API.
TOOL_NAME_PREFIX: Prepends slack_ to tool names (e.g., slack_get_users_info).

3. Resulting Tools

Example tools in FastMCP mode:

slack_get_users_info: Retrieves user info (e.g., for USLACKBOT).
slack_get_conversations_list: Lists channels in the workspace.
slack_post_chat_postmessage: Posts a message to a channel.

4. Testing

Test with environment variables:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json" API_KEY="<your_slack_bot_token>" API_KEY_JMESPATH="token" TOOL_NAME_PREFIX="slack_" TOOL_WHITELIST="/chat,/bots,/conversations,/reminders,/files,/users" uvx mcp-openapi-proxy

Try these commands in your MCP client:

List tools: list_functions.
Get Slackbot info: call_function slack_get_users_info '{"user": "USLACKBOT"}'.
Post a message: call_function slack_post_chat_postmessage '{"channel": "C12345678", "text": "G’day from MCP, ya legends!"}' (replace C12345678 with a valid channel ID your bot can access).

GetZep Example

GetZep offers a free cloud API for memory management with detailed endpoints. Since GetZep did not provide an official OpenAPI specification, this project includes a generated spec hosted on GitHub for convenience. This approach—creating a spec from documentation—is a reusable pattern: users can similarly generate OpenAPI specs for any REST API and reference them locally (e.g., file:///path/to/spec.json). Obtain an API key from GetZep's documentation.

1. Verify the OpenAPI Specification

Retrieve the project-provided GetZep OpenAPI specification:

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json

Ensure it’s a valid OpenAPI JSON document. Alternatively, generate your own spec and use file:// to point to a local file.

2. Configure mcp-openapi-proxy for GetZep

Update your configuration:

{
    "mcpServers": {
        "getzep": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json",
                "TOOL_WHITELIST": "/sessions",
                "API_KEY": "<your_getzep_api_key>",
                "API_AUTH_TYPE": "Api-Key",
                "SERVER_URL_OVERRIDE": "https://api.getzep.com",
                "TOOL_NAME_PREFIX": "getzep_"
            }
        }
    }
}

OPENAPI_SPEC_URL: Points to the project-provided GetZep Swagger spec (or use file:///path/to/your/spec.json for a local file).
TOOL_WHITELIST: Limits to /sessions endpoints.
API_KEY: Your GetZep API key.
API_AUTH_TYPE: Uses Api-Key for header-based authentication (overrides default Bearer).
SERVER_URL_OVERRIDE: GetZep’s API base URL.
TOOL_NAME_PREFIX: Prepends getzep_ to tools.

3. Resulting Tools

Example tools:

getzep_post_sessions: Adds a session.
getzep_get_sessions_memory: Retrieves session memory.

Full list (abbreviated):

{
  "tools": [
    {
      "name": "getzep_post_sessions",
      "description": "Add Session",
      "inputSchema": {"type": "object", "properties": {}, "required": []}
    },
    {
      "name": "getzep_get_sessions_memory",
      "description": "Get Session Memory",
      "inputSchema": {
        "type": "object",
        "properties": {
          "sessionId": {"type": "string", "description": "ID of the session"},
          "lastn": {"type": "integer", "description": "Number of recent entries"}
        },
        "required": ["sessionId"]
      }
    }
  ]
}

4. Testing

Verify with the hosted spec:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json" API_KEY="<your_getzep_api_key>" API_AUTH_TYPE="Api-Key" uvx mcp-openapi-proxy

Or with a local spec:

OPENAPI_SPEC_URL="file:///path/to/your/getzep.swagger.json" API_KEY="<your_getzep_api_key>" API_AUTH_TYPE="Api-Key" uvx mcp-openapi-proxy

Troubleshooting

Missing OPENAPI_SPEC_URL: Ensure it’s set to a valid OpenAPI JSON URL or local file path.
Invalid Specification: Verify the OpenAPI document is standard-compliant.
Tool Filtering Issues: Check TOOL_WHITELIST matches desired endpoints.
Authentication Errors: Confirm API_KEY, API_KEY_JMESPATH, and API_AUTH_TYPE are correct.
Logging: Set DEBUG=true for detailed output to stderr.
Test Server: Run directly:

uvx 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.1741472270

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.1741472270
File	Size	Uploaded	Provenance
mcp_openapi_proxy-0.1.1741472270.tar.gz	19.4 kB	Mar 8, 2025	Without provenance	Details

Built distribution (wheel)

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

Total release size: 37.7 kB

Release files / mcp_openapi_proxy-0.1.1741472270.tar.gz

Download URL	mcp_openapi_proxy-0.1.1741472270.tar.gz
Size	19.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`d565f19d4198b1440ce8bdfb0095012ee96ae1fd28b42e537aed8b3ba54eba28`
BLAKE2b-256 checksum How to use checksums	`d917ceed81de76eddb58f111d4fa0c64a7b68600d329c130cac21cf157cdb535`
Upload date	Mar 8, 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.1741472270-py3-none-any.whl

Download URL	mcp_openapi_proxy-0.1.1741472270-py3-none-any.whl
Size	18.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3f6b719fc1942a556ab5548ee67935adc14b0d5fe97d8efd2e39d6802b10c4db`
BLAKE2b-256 checksum How to use checksums	`fc9f44ced93635a161e307046c041e01aa9ca9ab6f930e507c03888d45000caa`
Upload date	Mar 8, 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.1741472270

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.