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.

Table of Contents

• Overview
• Features
• Installation
  • MCP Ecosystem Integration
• Modes of Operation
  • FastMCP Mode (Simple Mode)
  • Low-Level Mode (Default)
• Environment Variables
• Examples
  • Glama Example
  • Fly.io Example
  • Render Example
  • Slack Example
  • GetZep Example
  • Notion Example
  • Asana Example
• Troubleshooting
• License

Overview

The package offers two operational modes:

• Low-Level Mode (Default): Dynamically registers tools corresponding to all valid API endpoints specified in an OpenAPI document (e.g. /chat/completions becomes chat_completions()).
• FastMCP Mode (Simple Mode): Provides a streamlined approach by 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:

MCP Ecosystem Integration

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

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_AUTH_TYPE: (Optional) Overrides the default Bearer Authorization header type (e.g. Api-Key for GetZep).
• STRIP_PARAM: (Optional) JMESPath expression to strip unwanted parameters (e.g. token for Slack).
• DEBUG: (Optional) Enables verbose debug logging when set to "true", "1", or "yes".
• EXTRA_HEADERS: (Optional) Additional HTTP headers in "Header: Value" format (one per line) to attach to outgoing API requests.
• SERVER_URL_OVERRIDE: (Optional) Overrides the base URL from the OpenAPI specification when set, useful for custom deployments.
• Additional Variable: OPENAPI_SPEC_URL_<hash> – a variant for unique per-test configurations (falls back to OPENAPI_SPEC_URL).

Examples

For testing you can run the uvx command as demonstrated in the examples then interact with the MCP server via JSON-RPC messages to list tools and resources. See the "JSON-RPC Testing" section below.

Glama Example

Glama offers the most minimal configuration for mcp-openapi-proxy requiring only the OPENAPI_SPEC_URL environment variable. This simplicity makes it ideal for quick testing.

1. Verify the OpenAPI Specification

Retrieve the Glama OpenAPI specification:

Ensure the response is a valid OpenAPI JSON document.

2. Configure mcp-openapi-proxy for Glama

Add the following configuration to your MCP ecosystem settings:

3. Testing

Start the service with:

Then refer to the JSON-RPC Testing section for instructions on listing resources and tools.

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:

Ensure the response is a valid OpenAPI JSON document.

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

Update your MCP ecosystem configuration:

• OPENAPI_SPEC_URL: Points to the Fly.io OpenAPI specification.
• API_KEY: Your Fly.io API token (replace <your_flyio_token_here>).
• API_AUTH_TYPE: Set to Api-Key for Fly.io’s header-based authentication (overrides default Bearer).

3. Testing

After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Render Example

Render offers infrastructure hosting that can be managed via an API. The provided configuration file examples/render-claude_desktop_config.json demonstrates how to set up your MCP ecosystem quickly with minimal settings.

1. Verify the OpenAPI Specification

Retrieve the Render OpenAPI specification:

Ensure the response is a valid OpenAPI document.

2. Configure mcp-openapi-proxy for Render

Add the following configuration to your MCP ecosystem settings:

3. Testing

Launch the proxy with your Render configuration:

After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Slack Example

Slack’s API showcases stripping unnecessary token payload using JMESPath. Obtain a bot token from Slack API documentation.

1. Verify the OpenAPI Specification

Retrieve the Slack OpenAPI specification:

Ensure it’s a valid OpenAPI JSON document.

2. Configure mcp-openapi-proxy for Slack

Update your configuration:

• 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>).
• STRIP_PARAM: Removes the token field from the request payload (as it is handled in the HTTP header).
• TOOL_NAME_PREFIX: Prepends slack_ to tool names (e.g. slack_get_users_info).

3. Resulting Functions

Example functions in FastMCP mode:

• slack_get_users_info: Retrieves user info.
• slack_get_conversations_list: Lists channels in the workspace.
• slack_post_chat_postmessage: Posts a message to a channel.

4. Testing

After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.

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. 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:

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

2. Configure mcp-openapi-proxy for GetZep

Update your configuration:

• 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).
• TOOL_NAME_PREFIX: Prepends getzep_ to tool names.

3. Resulting Functions

Example functions:

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

4. Testing

After starting the service refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Notion Example

Notion’s API requires specifying a particular version via HTTP headers. This example uses the EXTRA_HEADERS environment variable to include the required header, and focuses on verifying the OpenAPI specification.

1. Verify the OpenAPI Specification

Retrieve the Notion OpenAPI specification:

Ensure the response is a valid YAML document.

2. Configure mcp-openapi-proxy for Notion

Add the following configuration to your MCP ecosystem settings:

3. Testing

Launch the proxy with the Notion configuration:

After starting the service, refer to the JSON-RPC Testing section for instructions on listing resources and tools.

Asana Example

Asana provides a rich set of endpoints for managing workspaces, tasks, projects, and users. The integration tests demonstrate usage of endpoints such as GET /workspaces, GET /tasks, and GET /projects.

1. Verify the OpenAPI Specification

Retrieve the Asana OpenAPI specification:

Ensure the response is a valid YAML (or JSON) document.

2. Configure mcp-openapi-proxy for Asana

Add the following configuration to your MCP ecosystem settings:

3. Testing

Before running integration tests, ensure you have a valid ASANA_API_KEY set in your environment (e.g. in your .env file). Then start the proxy with:

Use MCP tools (via JSON-RPC messages or client libraries) to interact with the Asana endpoints, such as listing workspaces, tasks, and projects, as demonstrated in the integration tests.

Troubleshooting

JSON-RPC Testing

For alternative testing you can interact with the MCP server via JSON-RPC. After starting the server, paste the following initialization message:

Expected response:

Then paste these follow-up messages:

• Missing OPENAPI_SPEC_URL: Ensure it’s set to a valid OpenAPI URL or local file path.
• Invalid Specification: Verify that the OpenAPI document meets standards.
• Tool Filtering Issues: Check that TOOL_WHITELIST matches the desired endpoints.
• Authentication Errors: Confirm that API_KEY and API_AUTH_TYPE are configured correctly.
• Logging: Set DEBUG=true for detailed logs.

To run the server directly:

License

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