mcp-rest-adaptor

mcp-rest-adaptor functions as a Python-based Model Context Protocol (MCP) listener service. Its core purpose is to dynamically materialize REST APIs, whose structure is described by OpenAPI specifications, into runnable MCP functions. This capability is crucial for incorporating external HTTP services directly into automated MCP orchestration pipelines.

Table of Contents

• Introduction
• Key Capabilities
• Setup and Installation
• Integration into MCP Fabric
• Operational Modalities
• Accelerated MCP Mode (Fast Mode)
• Detailed Mode (Default)
• Configuration Environment Variables
• Use Cases and Implementations
• Glama Integration Profile
• Fly.io Service Profile
• Render Platform Profile
• Slack API Profile
• Zep Memory Service Profile
• VirusTotal Scanning Profile
• Notion Database Profile
• Asana Task Management Profile
• APIs.guru Directory Access
• NetBox DCIM Integration
• Box Cloud Storage Profile
• WolframAlpha Computation Profile
• Error Resolution
• Licensing

Introduction

This package presents two primary operational paradigms:

• Detailed Mode (Default): Introspects the entirety of a provided OpenAPI definition, converting every conforming endpoint (e.g., translating a path like /v1/models to an MCP function v1_models()) into an executable tool.
• Accelerated MCP Mode (Fast Mode): Utilizes static configuration to expose a minimal, predefined set of functions (query_service() and invoke_endpoint()), favoring speed and simplicity over granular endpoint exposure.

Key Capabilities

• Schema-Driven Tooling: Automatic creation of MCP primitives directly from OpenAPI definitions.
• Simplicity Option: FastMCP mode provides a static, low-overhead tooling structure.
• Specification Compliance: Supports OpenAPI Specification version 3, with backward compatibility for v2.
• Selective Exposure: Path filtering via inclusion lists (whitelisting) is supported.
• Payload-Based Authorization: Allows leveraging JMESPath for extracting authentication credentials directly from input data (useful for services like Slack).
• Standard Header Authorization: Defaults to using Bearer <API_KEY> in the Authorization header, but is configurable for non-standard schemes (e.g., Api-Key for Fly.io).
• Native MCP Embedding: Designed for fluid incorporation into existing MCP infrastructures.

Setup and Installation

Install the package via the standard distribution manager:

bash uvx mcp-rest-adaptor

Integration into MCP Fabric

To onboard mcp-rest-adaptor into your orchestration environment, define it within your mcpServers manifest. A general configuration template is shown below:

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

Consult the specific Use Cases section for tailored configuration examples.

Operational Modalities

Accelerated MCP Mode (Fast Mode)

• Activation: Set the environment variable OPENAPI_SIMPLE_MODE to true.
• Functionality: Exposes only a fixed subset of tools determined by internal code definitions.
• Configuration: Behavior is primarily dictated by external environment settings.

Detailed Mode (Default)

• Functionality: Maps every permissible endpoint found within the input OpenAPI schema to a unique tool.
• Tool Naming Convention: Tool names are derived via normalization of the schema path segments and HTTP method.
• Documentation: Tool summaries and descriptions are populated from the corresponding OpenAPI operation documentation fields.

Configuration Environment Variables

• OPENAPI_SPEC_URL: (Mandatory) URI pointing to the OpenAPI definition file (can be remote HTTP(S) or local file://).
• OPENAPI_LOGFILE_PATH: (Optional) Destination path for logging output.
• OPENAPI_SIMPLE_MODE: (Optional) If present and set to true, activates FastMCP operational mode.
• TOOL_WHITELIST: (Optional) Comma-separated list of full endpoint paths to include in tool generation.
• TOOL_NAME_PREFIX: (Optional) A string prepended to all generated tool identifiers.
• API_KEY: (Optional) Secret credential, defaulted to being sent as Bearer <API_KEY> in the Authorization header.
• API_AUTH_TYPE: (Optional) Overrides the default Bearer scheme (e.g., use Api-Key for systems expecting a proprietary header value).
• STRIP_PARAM: (Optional) A JMESPath expression specifying input parameters to omit from the final request body (e.g., removing redundant authentication fields).
• DEBUG: (Optional) Enables verbose diagnostic logging when set to non-falsy values (true, 1, yes).
• EXTRA_HEADERS: (Optional) Specifies additional HTTP headers to inject into outgoing requests, one header per line in Name: Value format.
• SERVER_URL_OVERRIDE: (Optional) Overwrites the base server URL specified within the OpenAPI document, essential for deployments behind proxies or custom hosts.
• TOOL_NAME_MAX_LENGTH: (Optional) Limits the length of generated tool names.
• Auxiliary Variant: OPENAPI_SPEC_URL_<hash> – allows per-test or environment-specific overrides for the main specification URL.
• IGNORE_SSL_SPEC: (Optional) If true, bypasses SSL certificate validation when retrieving the OpenAPI specification document.
• IGNORE_SSL_TOOLS: (Optional) If true, bypasses SSL certificate validation for API calls executed by the generated tools.

Use Cases and Implementations

For development testing, execution can often be initiated directly via the command line as shown in the examples, followed by interaction with the MCP server using standard JSON-RPC messages (see Testing section).

Glama Integration Profile

Glama requires the simplest setup, primarily needing only the specification URL.

1. Specification Validation

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

2. Configuration Snippet

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

3. Execution

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

Fly.io Service Profile

Fly.io provides machine lifecycle management via its API. Authentication requires a token obtained via flyctl.

1. Specification Retrieval

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

2. Configuration Snippet

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

Key Directives: - API_KEY: Insert your Fly.io credential. - API_AUTH_TYPE: Must be set to Api-Key to satisfy Fly.io’s header requirement, overriding the default Bearer structure.

Render Platform Profile

Configuration for managing Render infrastructure resources.

1. Specification Retrieval

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

2. Configuration Snippet

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

Slack API Profile

This profile illustrates using STRIP_PARAM to clean up request payloads, specifically removing the redundant authentication token from the body when using header authentication.

1. Specification Retrieval

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

2. Configuration Snippet

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

Zep Memory Service Profile

GetZep provides stateful memory services. As an official spec may be absent, this uses a community-generated one.

1. Specification Retrieval

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

2. Configuration Snippet

{ "mcpServers": { "zep_memory": { "command": "uvx", "args": ["mcp-rest-adaptor"], "env": { "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/getzep.swagger.json", "TOOL_WHITELIST": "/sessions", "API_KEY": "", "API_AUTH_TYPE": "Api-Key", "TOOL_NAME_PREFIX": "zep_" } } } }

VirusTotal Scanning Profile

This example highlights handling YAML specifications and using a non-standard authentication header (x-apikey).

1. Specification Retrieval

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

2. Configuration Snippet

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

Important Note: Since the standard mechanism sends keys as Authorization: Bearer ..., custom headers like VirusTotal's require explicit inclusion via EXTRA_HEADERS (and often disabling the default header mechanism).

Notion Database Profile

Notion API requires specific version negotiation via custom HTTP headers.

1. Specification Retrieval

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

2. Configuration Snippet

{ "mcpServers": { "notion_client": { "command": "uvx", "args": [ "mcp-rest-adaptor" ], "env": { "API_KEY": "ntn_", "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" } } } }

Asana Task Management Profile

Integration with Asana's work management APIs.

1. Specification Retrieval

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

2. Configuration Snippet

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

APIs.guru Directory Access

Leveraging APIs.guru as a metadata source to dynamically expose many other APIs.

1. Specification Retrieval

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

2. Configuration Snippet

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

NetBox DCIM Integration

Integrating the IPAM/DCIM capabilities of NetBox.

1. Specification Retrieval

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

2. Configuration Snippet

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

Box Cloud Storage Profile

Exposing Box Platform features, requiring a developer token for authorization.

Example configuration for Box integration:

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

Instruction: Configure BOX_API_KEY in your secrets management system.

WolframAlpha Computation Profile

Integration requires an application ID for computation requests.

Example configuration for WolframAlpha:

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

Instruction: Set WOLFRAM_LLM_APP_ID to your unique application identifier.

Error Resolution

JSON-RPC Testing Interface

Direct interaction with the service via JSON-RPC can validate functionality after startup.

Initialization Message:

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

Confirmation:

{"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 Queries:

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

• Specification Load Failures: Verify OPENAPI_SPEC_URL accessibility and format correctness (JSON vs. YAML).
• Tool Generation Gaps: Inspect the TOOL_WHITELIST configuration against paths in the source specification.
• Auth Failures: Systematically check API_KEY validity and confirm API_AUTH_TYPE matches remote server expectations.
• Debugging Verbosity: Activate detailed tracing by setting DEBUG="true".
• Direct Execution: For immediate testing:

bash uvx mcp-rest-adaptor

Licensing

This project is distributed under the MIT License.

WIKIPEDIA SUMMARY: The XMLHttpRequest (XHR) object provides a standardized JavaScript interface for making asynchronous HTTP requests to a server, central to Ajax programming. Introduced by Microsoft in IE5 (1999) using ActiveX objects, it became a cross-browser standard supported by W3C. XHR usage involves instantiating the object, configuring the request type and URL using open(), setting up event handlers for state changes, and dispatching the request with send(). It enables dynamic page updates without full reloads.