codex exec \
  -c 'mcp_servers.glama.command="uvx"' \
  -c 'mcp_servers.glama.args=["mcp-openapi-proxy"]' \
  -c 'mcp_servers.glama.env.OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json"' \
  "list the available tools"

{
  "mcpServers": {
    "glama": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

{
  "mcpServers": {
    "glama": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

{
  "mcpServers": {
    "glama": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

{
  "mcp": {
    "glama": {
      "type": "local",
      "command": ["uvx", "mcp-openapi-proxy"],
      "environment": { "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json" }
    }
  }
}

[[mcp_servers]]
name = "glama"
command = "uvx"
args = ["mcp-openapi-proxy"]

[mcp_servers.env]
OPENAPI_SPEC_URL = "https://glama.ai/api/mcp/openapi.json"

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:

curl https://glama.ai/api/mcp/openapi.json

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:

{
    "mcpServers": {
        "glama": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://glama.ai/api/mcp/openapi.json"
            }
        }
    }
}

3. Testing

Start the service with:

OPENAPI_SPEC_URL="https://glama.ai/api/mcp/openapi.json" uvx mcp-openapi-proxy

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

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>"
            }
        }
    }
}

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

curl https://api-docs.render.com/openapi/render-public-api-1.json

Ensure the response is a valid OpenAPI document.

2. Configure mcp-openapi-proxy for Render

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "render": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://api-docs.render.com/openapi/render-public-api-1.json",
                "TOOL_WHITELIST": "/services,/maintenance",
                "API_KEY": "your_render_token_here"
            }
        }
    }
}

3. Testing

Launch the proxy with your Render configuration:

OPENAPI_SPEC_URL="https://api-docs.render.com/openapi/render-public-api-1.json" TOOL_WHITELIST="/services,/maintenance" API_KEY="your_render_token_here" uvx mcp-openapi-proxy

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

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:

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, starts with xoxb>",
                "STRIP_PARAM": "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>).
• STRIP_PARAM: Removes the token field from the request payload.
• TOOL_NAME_PREFIX: Prepends slack_ to tool names.

3. Testing

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

Note (2026): GetZep's hosted endpoint (api.getzep.com) returns 401 for previously-working keys — the hosted free tier no longer accepts API keys. The example now targets a self-hosted Zep CE: see examples/zep-ce/docker-compose.yml (zep built from source tag v1.0.2 + pgvector/pgvector:pg17; the delisted zepai/zep image must be rebuilt via the official Dockerfile.ce). Auth quirk: Zep's scheme is literally Api-Key, which collides with the proxy's special api-key mode — use API_AUTH_TYPE=api-key with API_KEY="Api-Key <your-secret>". Live-verified: 8 tools via TOOL_WHITELIST=/sessions; session create + read-back through the bridge.

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:

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 a file:// URL to reference 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",
                "TOOL_NAME_PREFIX": "zep_"
            }
        }
    }
}

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

3. Testing

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

This example demonstrates:

• Using a YAML OpenAPI specification file
• Using custom HTTP auth header, "x-apikey"

1. Verify the OpenAPI Specification

Retrieve the Virustotal OpenAPI specification:

curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml

Ensure that the response is a valid OpenAPI YAML document.

2. Configure mcp-openapi-proxy for Virustotal

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "virustotal": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml",
                "EXTRA_HEADERS": "x-apikey: ${VIRUSTOTAL_API_KEY}",
                "OPENAPI_SPEC_FORMAT": "yaml"
            }
        }
    }
}

Key configuration points:

• By default, the proxy expects a JSON specification and sends the API key with a Bearer prefix.
• To use a YAML OpenAPI specification, include OPENAPI_SPEC_FORMAT="yaml".
• Note: VirusTotal requires a special authentication header; EXTRA_HEADERS is used to transmit the API key as "x-apikey: ${VIRUSTOTAL_API_KEY}".

3. Testing

Launch the proxy with the Virustotal configuration:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/virustotal.openapi.yml" API_KEY="your_virustotal_api_key" API_AUTH_HEADER="x-apikey" API_AUTH_TYPE="" OPENAPI_SPEC_FORMAT="yaml" uvx mcp-openapi-proxy

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

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:

curl https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml

Ensure the response is a valid YAML document.

2. Configure mcp-openapi-proxy for Notion

Add the following configuration to your MCP ecosystem settings:

{
  "mcpServers": {
    "notion": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
          "API_KEY": "ntn_<your_key>",
          "OPENAPI_SPEC_URL": "https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml",
          "SERVER_URL_OVERRIDE": "https://api.notion.com",
          "EXTRA_HEADERS": "Notion-Version: 2022-06-28"
      }
    }
  }
}

3. Testing

Launch the proxy with the Notion configuration:

OPENAPI_SPEC_URL="https://storage.googleapis.com/versori-assets/public-specs/20240214/NotionAPI.yml" SERVER_URL_OVERRIDE="https://api.notion.com" EXTRA_HEADERS="Notion-Version: 2022-06-28" API_KEY="ntn_<your_key>" uvx mcp-openapi-proxy

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

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:

curl https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml

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:

{
  "mcpServers": {
    "asana": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml",
        "SERVER_URL_OVERRIDE": "https://app.asana.com/api/1.0",
        "TOOL_WHITELIST": "/workspaces,/tasks,/projects,/users",
        "API_KEY": "${ASANA_API_KEY}"
      }
    }
  }
}

Note: Most Asana API endpoints require authentication. Set ASANA_API_KEY in your environment or .env file with a valid token.

3. Testing

Start the service with:

ASANA_API_KEY="<your_asana_api_key>" OPENAPI_SPEC_URL="https://raw.githubusercontent.com/Asana/openapi/refs/heads/master/defs/asana_oas.yaml" SERVER_URL_OVERRIDE="https://app.asana.com/api/1.0" TOOL_WHITELIST="/workspaces,/tasks,/projects,/users" uvx mcp-openapi-proxy

You can then use the MCP ecosystem to list and invoke tools for endpoints like /dcim/devices/ and /ipam/ip-addresses/.

APIs.guru provides a directory of OpenAPI definitions for thousands of public APIs. This example shows how to use mcp-openapi-proxy to expose the APIs.guru directory as MCP tools.

1. Verify the OpenAPI Specification

Retrieve the APIs.guru OpenAPI specification:

curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml

Ensure the response is a valid OpenAPI YAML document.

2. Configure mcp-openapi-proxy for APIs.guru

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "apisguru": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml"
            }
        }
    }
}

3. Testing

Start the service with:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/apis.guru/2.2.0/openapi.yaml" uvx mcp-openapi-proxy

You can then use the MCP ecosystem to list and invoke tools such as listAPIs, getMetrics, and getProviders that are defined in the APIs.guru directory.

NetBox is an open-source IP address management (IPAM) and data center infrastructure management (DCIM) tool. This example demonstrates how to use mcp-openapi-proxy to expose the NetBox API as MCP tools.

1. Verify the OpenAPI Specification

Retrieve the NetBox OpenAPI specification:

curl https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml

Ensure the response is a valid OpenAPI YAML document.

2. Configure mcp-openapi-proxy for NetBox

Add the following configuration to your MCP ecosystem settings:

{
    "mcpServers": {
        "netbox": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml",
                "API_KEY": "${NETBOX_API_KEY}"
            }
        }
    }
}

Note: Most NetBox API endpoints require authentication. Set NETBOX_API_KEY in your environment or .env file with a valid token.

3. Testing

Start the service with:

OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/netbox.dev/3.4/openapi.yaml" API_KEY="$NETBOX_API_KEY" uvx mcp-openapi-proxy

You can then use the MCP ecosystem to list and invoke tools for endpoints like /dcim/devices/ and /ipam/ip-addresses/.

You can integrate the Box Platform API using your own developer token for authenticated access to your Box account. This example demonstrates how to expose Box API endpoints as MCP tools.

Example config: examples/box-claude_desktop_config.json

"env": {
  "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml",
  "TOOL_WHITELIST": "/folders/{folder_id}/items,/files/{file_id},/search,/recent_items",
  "API_KEY": "${BOX_API_KEY}"
}

• Set your Box developer token as an environment variable in .env:

  BOX_API_KEY=your_box_developer_token
  

• Or run the proxy with a one-liner:

  OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/box.com/2.0.0/openapi.yaml" API_KEY="$BOX_API_KEY" uvx mcp-openapi-proxy
  

You can now use the MCP ecosystem to list and invoke Box API tools. For integration tests, see tests/integration/test_box_integration.py.

Note: developer api keys for free tier box users are limited to 60 minutes :(.

You can integrate the WolframAlpha API using your own App ID for authenticated access. This example demonstrates how to expose WolframAlpha API endpoints as MCP tools.

Example config: examples/wolframalpha-claude_desktop_config.json

{
  "mcpServers": {
    "wolframalpha": {
      "command": "uvx",
      "args": [
        "mcp-openapi-proxy"
      ],
      "env": {
        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/wolframalpha.com/v0.1/openapi.yaml",
        "API_KEY": "${WOLFRAM_LLM_APP_ID}"
      }
    }
  }
}

• Set your WolframAlpha App ID as an environment variable in .env:

  WOLFRAM_LLM_APP_ID=your_wolfram_app_id
  

• Or run the proxy with a one-liner:

  OPENAPI_SPEC_URL="https://raw.githubusercontent.com/APIs-guru/openapi-directory/refs/heads/main/APIs/wolframalpha.com/v0.1/openapi.yaml" API_KEY="$WOLFRAM_LLM_APP_ID" uvx mcp-openapi-proxy
  

You can now use the MCP ecosystem to list and invoke WolframAlpha API tools. For integration tests, see tests/integration/test_wolframalpha_integration.py.

Letta runs agents on a server, so attachment differs by deployment:

• Self-hosted Letta accepts a stdio MCP server via PUT /v1/tools/mcp/servers — no network exposure.
• Letta Cloud rejects stdio and needs a remote streamable-HTTP MCP URL behind authentication.

Both were verified live (an agent autonomously called get_v1_attributes from the Glama spec through the proxy). Full setup for both paths, including the supergateway wrapper and the security note for the Cloud endpoint, is in examples/letta/README.md.

This example turns the WordPress REST API into MCP tools so an agent can create, read, update, and trash blog posts. It is the example behind a real-world demonstration: a fleet of agent CLIs published to the live blog at matthewhand.mywebcommunity.org through this proxy — see the write-up “Turning Any API into Agent Tools”, itself posted via the proxy.

Example config — examples/wordpress-claude_desktop_config.json:

{
  "mcpServers": {
    "wordpress": {
      "command": "uvx",
      "args": ["mcp-openapi-proxy"],
      "env": {
        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/main/examples/wordpress-openapi.json",
        "SERVER_URL_OVERRIDE": "https://your-site.example.com/wp-json",
        "EXTRA_HEADERS": "Authorization: Basic BASE64_OF_USERNAME_COLON_APPLICATION_PASSWORD",
        "IGNORE_SSL_TOOLS": "false",
        "TOOL_WHITELIST": "/wp/v2/posts"
      }
    }
  }
}

Exposed tools (from the bundled examples/wordpress-openapi.json): get_wp_v2_posts, post_wp_v2_posts (create), get_wp_v2_posts_by_id, post_wp_v2_posts_by_id (update), and delete_wp_v2_posts_by_id (trash) — the full post lifecycle.

Auth — use a WordPress Application Password, not your login password. WordPress REST rejects login passwords for Basic auth. In wp-admin → Users → (your user) → Application Passwords, create one, then base64-encode username:application-password for the EXTRA_HEADERS value:

printf 'myuser:xxxx xxxx xxxx xxxx xxxx xxxx' | base64 -w0

Tips: set IGNORE_SSL_TOOLS=true only if your host serves a self-signed/mismatched cert; give each agent its own (revocable) application password; keep TOOL_WHITELIST=/wp/v2/posts so the agent can touch only posts.

Exposes a generic slice of the Home Assistant REST API (21 operations) — read state (get_config, list_states, get_state, list_services, get_history/get_history_now, get_logbook, list_calendars, get_calendar_events, get_camera_image, get_error_log, list_components, list_events, get_api_status) and act (call_service, set_state, delete_state, fire_event, render_template, check_config, handle_intent). HA ships no official OpenAPI spec, so this is hand-rolled from the official docs.

1. Verify the OpenAPI specification

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

2. Configure mcp-openapi-proxy for Home Assistant

{
    "mcpServers": {
        "homeassistant": {
            "command": "uvx",
            "args": ["mcp-openapi-proxy"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json",
                "SERVER_URL_OVERRIDE": "http://homeassistant.local:8123",
                "API_KEY": "${HA_TOKEN}"
            }
        }
    }
}

Key configuration points:

• SERVER_URL_OVERRIDE — your instance base URL, e.g. http://homeassistant.local:8123 or http://<ha-host>:8123.
• HA_TOKEN — a Home Assistant long-lived access token (Profile → Long-Lived Access Tokens), passed via API_KEY; the proxy sends it as Authorization: Bearer <token> (its default scheme), so no EXTRA_HEADERS needed. Never commit the token; keep it in your environment.
• call_service requires mcp-openapi-proxy >= 0.3.3: earlier versions leaked the {domain}/{service} path params into the JSON body, which Home Assistant rejects with HTTP 400.

3. Testing

get_config should return your HA configuration (200). call_service for light/turn_on with body {"entity_id": "light.kitchen"} should return 200 — the path params land in the URL (/api/services/light/turn_on), not the body.