ControlAPI

ControlAPI MCP exposes any OpenAPI/REST API as MCP tools with dynamic server switching and variable substitution. It lets you connect to multiple API servers at once, reuse your authentication tokens, and reuse a consistent toolset to interact with different environments (dev, staging, prod).

How to use

You interact with the MCP server from your MCP client by configuring one or more server connectors, then using the built-in tools to discover endpoints, test requests, and manage variables. Start with connecting to an API server, then switch between servers as you test across environments. Use the variable substitution features to inject tokens or other dynamic values into headers, bodies, or paths.

How to install

Prerequisites you need before installing: Python 3.x, npm and/or a working shell, and curl for optional quick-start steps.

# Development setup (Python)
pip install -e .

# Build binary (produces dist/controlapi-mcp)
./build.sh

# Run the built binary (example usage shown in the config below)
dist/controlapi-mcp

Using Binary

If you prefer a prebuilt binary, you can run the MCP adapter directly and configure it to point at your API. The following example starts the binary and passes environment variables to set up the API URL and base URL.

{
  "servers": {
    "controlapi-mcp": {
      "type": "stdio",
      "command": "/path/to/openapi-mcp-adapter/dist/controlapi-mcp",
      "env": {
        "OPENAPI_URL": "http://localhost:8000/openapi.json",
        "BASE_URL": "http://localhost:8000",
        "DEBUG_PORT": "45133"
      }
    }
  }
}

Using Python (Development)

If you want to run the MCP server from Python in development, use the Python module entry point. This setup is useful when you’re actively developing the adapter.

{
  "servers": {
    "controlapi-mcp": {
      "type": "stdio",
      "command": "/path/to/project/.venv/bin/python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/project",
      "env": {
        "OPENAPI_URL": "http://localhost:8000/openapi.json",
        "REFRESH_INTERVAL": "300",
        "PYTHONPATH": "/path/to/project",
        "BASE_URL": "http://localhost:8000",
        "DEBUG_PORT": "45133"
      }
    }
  }
}

Quick start with auto-download

You can run the latest release without installing anything locally by using an auto-run script. The script downloads and starts the MCP server automatically.

curl -O https://raw.githubusercontent.com/fellowabhi/ControlAPI-openapi-to-mcp/main/auto-run.sh
chmod +x auto-run.sh

{
  "servers": {
    "controlapi-mcp": {
      "type": "stdio",
      "command": "/path/to/auto-run.sh"
    }
  }
}

Optional environment variables and dynamic setup

You can optionally set OPENAPI_URL, BASE_URL, and SERVER_NICKNAME in environment variables, or configure dynamically using the set_server_config tool. You can also adjust DEBUG_PORT to a port you prefer.

Example workflow

1. Connect to an API by running a server config with set_server_config and providing the openapi_url. 2. Make a request to /auth/login with execute_request to obtain a token. 3. Store the token with set_variable. 4. Reuse the token in subsequent requests using {{token}} in headers. 5. Switch to a different environment by running set_server_config again to point at dev, staging, or production.

Notes on debugging and monitoring

A browser-based debug UI is available at the port you specify in DEBUG_PORT (default 45133). Open http://localhost:45133 to inspect request/response flows while testing your API.

Available tools

set_server_config

Connect to an OpenAPI server, establishing an initial MCP context for subsequent actions.

get_server_info

Check the current server and connection status to verify active API source.

get_server_history

View the history of recently connected servers and context switches.

health_check

Test connectivity to the active OpenAPI server to ensure availability.

list_endpoints

List all endpoints defined by the OpenAPI schema for quick reference.

search_schema

Search endpoints by keyword to locate relevant API operations.

execute_request

Make HTTP requests with automatic variable substitution in headers, path, and body.

set_variable

Store a value (for example an auth token) for reuse in subsequent requests.

get_variables

View all stored variables available for substitution.

reload_schema

Reload the current server's OpenAPI schema to reflect changes.