mcp-rest-adapter: Bridging OpenAPI Specs to MCP Services

mcp-rest-adapter is a specialized Python utility designed to function as an MCP server. Its primary objective is to introspect OpenAPI (formerly Swagger) descriptive documents and automatically materialize the documented RESTful interfaces as invokeable MCP tools. This mechanism allows complex external APIs to be managed and utilized directly within MCP-orchestrated processes.

Table of Contents

• Core Functionality
• Key Features
• Acquisition & Setup
• Ecosystem Integration Guide
• Operational Modalities
• Rapid Execution Mode (Simple Mode)
• Granular Control Mode (Default)
• Configuration Variables (Environment)
• Practical Use Cases (Illustrations)
• Glama Integration Scenario
• Fly.io Deployment Scenario
• Render Infrastructure Management
• Slack Interaction Example
• Zep Memory Service Hookup
• VirusTotal File Scanning Example
• Notion Database Access Example
• Asana Task Orchestration
• APIs.guru Directory Browsing
• NetBox DCIM Bridging
• Box Cloud Storage Interface
• WolframAlpha Computation Interface
• Diagnostic Procedures
• Software License

Core Functionality

This package provides two distinct modes for API exposure:

• Granular Control Mode (Standard): Exhaustively generates dedicated MCP invocation functions for every permissible endpoint detailed in the input OpenAPI manifest (e.g., a definition at /users/{id} translates to a tool named users_id()).
• Rapid Execution Mode (Streamlined): Offers a simplified operational posture by exposing a minimal, hardcoded set of generic interaction functions (like query_endpoint() and execute_operation()) derived from static internal definitions.

Key Features

• Automated Tool Synthesis: Instantly constructs MCP tooling directly from OpenAPI service descriptions.
• Dual-Mode Operation: Provides flexibility between full dynamic mapping and simplified static function exposure.
• OpenAPI Compliance: Supports OpenAPI Specification version 3, with backward compatibility for v2.
• Selective Exposure: Enables endpoint inclusion/exclusion filtering via path whitelists or custom criteria.
• Token Handling (Payload): Supports injecting security tokens directly into request bodies using JMESPath evaluation (necessary for certain vendors like Slack).
• Token Handling (Header): Defaults to standard Bearer token placement in the Authorization header for provided API keys, configurable for non-standard schemes (e.g., Api-Key for Fly.io).
• MCP Native Integration: Achieves fluid integration, treating external REST operations as native MCP workflow components.

Acquisition & Setup

Install the software package via PyPI:

uvx mcp-rest-adapter

Ecosystem Integration Guide

To embed mcp-rest-adapter within your wider MCP infrastructure, declare it within the mcpServers section of your primary configuration manifest. Below is a generalized template:

{
    "mcpServers": {
        "mcp-rest-adapter": {
            "command": "uvx",
            "args": ["mcp-rest-adapter"],
            "env": {
                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
                "API_KEY": "${API_OPENAPI_KEY}"
            }
        }
    }
}

Consult the specific API illustrations detailed subsequently for tailored configuration examples.

Operational Modalities

Rapid Execution Mode (Simple Mode)

• Activation Criterion: Setting the environment variable OPENAPI_SIMPLE_MODE to "true".
• Functionality: Exposes a constrained set of predefined functions based on internal code mapping.
• Configuration Basis: Behavior is dictated predominantly by specific environment parameters.

Granular Control Mode (Default)

• Functionality: Systematically converts every permissible operation defined in the input OpenAPI manifest into a distinct, callable tool.
• Naming Convention: Tool identifiers are synthesized from normalized URL paths and HTTP methods.
• Documentation Source: Tool descriptions are derived directly from the OpenAPI document's summary and detail fields.

Configuration Variables (Environment)

• OPENAPI_SPEC_URL: (Mandatory) Location of the specification document (e.g., http://server/spec.json or file:///local/path/spec.json).
• OPENAPI_LOGFILE_PATH: (Optional) Destination file path for diagnostic logging.
• OPENAPI_SIMPLE_MODE: (Optional) Set to "true" to engage Rapid Execution Mode.
• TOOL_WHITELIST: (Optional) Comma-separated list of URI paths to process; anything not listed is ignored.
• TOOL_NAME_PREFIX: (Optional) A standardized prefix affixed to all generated tool names.
• API_KEY: (Optional) The principal secret credential transmitted in the Authorization header, defaulting to Bearer <key>.
• API_AUTH_TYPE: (Optional) Overrides the default Bearer scheme (e.g., use Api-Key for specific services).
• STRIP_PARAM: (Optional) A JMESPath expression defining payload parameters to omit before transmission (e.g., removing redundant authentication parameters).
• DEBUG: (Optional) Activates verbose, detailed logging when set to any truthy value ("true", "1", etc.).
• EXTRA_HEADERS: (Optional) Additional HTTP header pairs, formatted as Header-Name: Value, one per line, to append to all outgoing requests.
• SERVER_URL_OVERRIDE: (Optional) Replaces the base URL discovered within the OpenAPI document, useful for routing requests to alternative deployment targets.
• TOOL_NAME_MAX_LENGTH: (Optional) Imposes a length limit on generated tool names.
• Variant Variable: OPENAPI_SPEC_URL_<hash> – A specialized version for isolated testing setups, used before falling back to the primary OPENAPI_SPEC_URL.
• IGNORE_SSL_SPEC: (Optional) If set to "true", suppresses X.509 certificate validation when retrieving the OpenAPI definition file.
• IGNORE_SSL_TOOLS: (Optional) If set to "true", bypasses SSL validation checks for all downstream API calls executed by the tools.

Practical Use Cases (Illustrations)

To begin testing, initiate the adapter with the example setup and utilize JSON-RPC messaging to enumerate available resources and services. See the "JSON-RPC Diagnostics" section below.

Glama Integration Scenario

Glama requires only the specification URL for minimal setup, making it excellent for preliminary validation.

1. Specification Validation

Fetch the current Glama OpenAPI definition:

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

Verify the output conforms to OpenAPI JSON standards.

2. Configuration for Glama

Incorporate this block into your MCP environment settings:

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

3. Execution

Launch the adapter process:

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

Proceed to the JSON-RPC Testing section for service verification.

Fly.io Deployment Scenario

Fly.io's machine management API is a practical starting point. Secure your API credentials per Fly.io guidelines.

1. Specification Validation

Fetch the Fly.io machine specification:

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

2. Configuration for Fly.io

Adjust your MCP manifest:

{
    "mcpServers": {
        "flyio": {
            "command": "uvx",
            "args": ["mcp-rest-adapter"],
            "env": {
                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
                "API_KEY": "<your_flyio_secret>"
            }
        }
    }
}

• API_KEY: Your Fly.io secret (substitute <your_flyio_secret>).
• API_AUTH_TYPE: Explicitly set to Api-Key to meet Fly.io's header requirements.

3. Testing

After service initialization, verify functionality via JSON-RPC methods.

Render Infrastructure Management

Render enables cloud infrastructure management. The examples/render-claude_desktop_config.json file provides a streamlined setup demonstration.

1. Specification Validation

Fetch the Render specification document:

curl https://api-docs.render.com/openapi/6140fb3daeae351056086186

2. Configuration for Render

Update your MCP ecosystem configuration block:

{
    "mcpServers": {
        "render": {
            "command": "uvx",
            "args": ["mcp-rest-adapter"],
            "env": {
                "OPENAPI_SPEC_URL": "https://api-docs.render.com/openapi/6140fb3daeae351056086186",
                "TOOL_WHITELIST": "/services,/maintenance",
                "API_KEY": "your_render_secret_token"
            }
        }
    }
}

3. Testing

Execute the adapter utilizing the Render parameters:

OPENAPI_SPEC_URL="https://api-docs.render.com/openapi/6140fb3daeae351056086186" TOOL_WHITELIST="/services,/maintenance" API_KEY="your_render_token_here" uvx mcp-rest-adapter

Consult the JSON-RPC Testing section to confirm tool availability.

Slack Interaction Example

Slack's API integration highlights the use of JMESPath for sanitizing request payloads by eliminating the redundant token field.

1. Specification Validation

Acquire the Slack specification:

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

2. Configuration for Slack

Modify your environmental setup:

{
    "mcpServers": {
        "slack": {
            "command": "uvx",
            "args": ["mcp-rest-adapter"],
            "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_xoxb>",
                "STRIP_PARAM": "token",
                "TOOL_NAME_PREFIX": "slack_"
            }
        }
    }
}

• STRIP_PARAM: Ensures the token field is scrubbed from request bodies.
• TOOL_NAME_PREFIX: Adds a namespace prefix for clarity.

3. Testing

Initialize the adapter and verify tool listing via JSON-RPC.

Zep Memory Service Hookup

GetZep provides memory services. As an official spec may not be available, we use a community-generated one. Acquire your key from GetZep documentation.

1. Specification Validation

Retrieve the hosted Zep specification:

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

2. Configuration for GetZep

Adapt your environment settings:

{
    "mcpServers": {
        "getzep": {
            "command": "uvx",
            "args": ["mcp-rest-adapter"],
            "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_zep_api_key>",
                "API_AUTH_TYPE": "Api-Key",
                "TOOL_NAME_PREFIX": "zep_"
            }
        }
    }
}

• API_AUTH_TYPE: Configured for Api-Key header usage.

3. Testing

Start the proxy and check for session management tools.

VirusTotal File Scanning Example

This use case demonstrates: - Reading an OpenAPI specification in YAML format. - Injecting an API key via a custom HTTP header, specifically x-apikey.

1. Specification Validation

Fetch the Virustotal specification (YAML format):

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

2. Configuration for Virustotal

Register the service, noting the format and header overrides:

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

Key adjustments: - OPENAPI_SPEC_FORMAT="yaml" informs the parser to handle YAML. - EXTRA_HEADERS is used to place the key as required by VirusTotal.

3. Testing

Launch the adapter with the necessary parameters:

OPENAPI_SPEC_URL=".../virustotal.openapi.yml" API_KEY="your_vt_key" API_AUTH_TYPE="" OPENAPI_SPEC_FORMAT="yaml" uvx mcp-rest-adapter

(Note: API_AUTH_TYPE is cleared because EXTRA_HEADERS handles the key placement.)

Notion Database Access Example

Notion mandates API versioning transmitted in HTTP headers. This example configures a custom version header and overrides the base server URL.

1. Specification Validation

Retrieve the Notion specification (YAML):

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

2. Configuration for Notion

Configuration setup:

{
  "mcpServers": {
    "notion": {
      "command": "uvx",
      "args": [
        "mcp-rest-adapter"
      ],
      "env": {
          "API_KEY": "ntn_<your_notion_token>",
          "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 command:

OPENAPI_SPEC_URL="...NotionAPI.yml" SERVER_URL_OVERRIDE="https://api.notion.com" EXTRA_HEADERS="Notion-Version: 2022-06-28" API_KEY="ntn_<your_key>" uvx mcp-rest-adapter

Asana Task Orchestration

Asana offers robust management APIs for workspaces and tasks. Key endpoints like GET /workspaces are demonstrated.

1. Specification Validation

Fetch the Asana OpenAPI document:

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

2. Configuration for Asana

Configuration snippet:

{
  "mcpServers": {
    "asana": {
      "command": "uvx",
      "args": [
        "mcp-rest-adapter"
      ],
      "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}"
      }
    }
  }
}

Security Note: Ensure ${ASANA_API_KEY} is populated in your secure environment settings.

3. Testing

Run the adapter with environment variables:

ASANA_API_KEY="<your_asana_token>" OPENAPI_SPEC_URL="...asana_oas.yaml" SERVER_URL_OVERRIDE="https://app.asana.com/api/1.0" ... uvx mcp-rest-adapter

APIs.guru Directory Browsing

APIs.guru aggregates thousands of OpenAPI schemas, perfect for discovering new services.

1. Specification Validation

Fetch the APIs.guru index specification (YAML):

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

2. Configuration for APIs.guru

Simple configuration to expose the directory index:

{
    "mcpServers": {
        "apisguru": {
            "command": "uvx",
            "args": ["mcp-rest-adapter"],
            "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

Execute with the specification URL defined.

NetBox DCIM Bridging

NetBox, an IPAM/DCIM solution, can be exposed using its YAML specification.

1. Specification Validation

Retrieve the NetBox specification:

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

2. Configuration for NetBox

Standard configuration requiring a NetBox token:

{
    "mcpServers": {
        "netbox": {
            "command": "uvx",
            "args": ["mcp-rest-adapter"],
            "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}"
            }
        }
    }
}

3. Testing

Start the service, providing the NetBox API token.

Box Cloud Storage Interface

Integrate the Box Platform API using a developer token for authenticated access.

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

• Configure environment variable in .env: BOX_API_KEY=your_box_developer_token

• One-liner execution: bash OPENAPI_SPEC_URL="...box.com/2.0.0/openapi.yaml" API_KEY="$BOX_API_KEY" uvx mcp-rest-adapter

WolframAlpha Computation Interface

Integrate the WolframAlpha API, using your specific App ID for authorization.

Example config: examples/wolframalpha-claude_desktop_config.json

{
  "mcpServers": {
    "wolframalpha": {
      "command": "uvx",
      "args": [
        "mcp-rest-adapter"
      ],
      "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 App ID in environment: WOLFRAM_LLM_APP_ID=your_wolfram_app_id

• One-liner execution: bash OPENAPI_SPEC_URL="...wolframalpha.com/v0.1/openapi.yaml" API_KEY="$WOLFRAM_LLM_APP_ID" uvx mcp-rest-adapter

Diagnostic Procedures

JSON-RPC Diagnostics

To manually inspect the running service, send the following initialization sequence via JSON-RPC after starting the adapter:

Initialization Request:

{"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"claude-ai","version":"0.1.0"}},"jsonrpc":"2.0","id":0}

Expected Initialization Acknowledgment:

{"jsonrpc":"2.0","id":0,"result":{"protocolVersion":"2024-11-05","capabilities":{"experimental":{},"prompts":{"listChanged":false},"resources":{"subscribe":false,"listChanged":false},"tools":{"listChanged":false}},"serverInfo":{"name":"sqlite","version":"0.1.0"}}}

Subsequent Inspection Calls:

{"method":"notifications/initialized","jsonrpc":"2.0"}
{"method":"resources/list","params":{},"jsonrpc":"2.0","id":1}
{"method":"tools/list","params":{},"jsonrpc":"2.0","id":2}

• Configuration Failure: If OPENAPI_SPEC_URL is absent or invalid, the service will halt.
• Schema Error: Invalid OpenAPI structure will result in parsing failure logs.
• Filtering Error: Verify that path entries in TOOL_WHITELIST precisely match segments from the spec.
• Authorization Issues: Double-check API_KEY validity and that API_AUTH_TYPE matches the target server's expectation.
• Verbose Output: Set DEBUG="true" to output extensive operational details to standard error.
• Direct Execution Test:

uvx mcp-rest-adapter

Software License

MIT License

---

WIKIPEDIA CONTEXT NOTE: Business management solutions encompass all methodologies, applications, and systems utilized by enterprises to maintain market relevance, enhance competitiveness, and drive operational efficiency. These toolsets cover planning, process control, data aggregation for decision support, and resource management. Modern tool selection requires strategic alignment with organizational needs, rather than mere adoption of the newest technology, focusing on effective implementation and customization.