OpenAPI Services MCP server

mcp-openapix

<!-- mcp-name: io.github.alyiox/mcp-openapix -->

MCP server that fronts any OpenAPI service behind four generic tools.

An agent finds operations in each deployment's OpenAPI document and calls them; the server resolves the URL, obtains a bearer token, and builds the request. Discovery is listplatforms, listendpoints and describeendpoint; execution is the generic proxy callendpoint.

example / us / items / prod
  │     │     │      └── env ......... which deployment URL a call reaches
  │     │     └───────── service ..... one backend, one OpenAPI spec
  │     └─────────────── region ...... a geographic deployment
  └───────────────────── platform .... the product or API family

Requirements

• Python 3.13+ and uv
• A config.json describing the deployments you hold credentials for

Quick start

Set up your config (see Configuration), then run the server:

# Run directly with uvx (no clone needed)
npx -y @modelcontextprotocol/inspector@latest uvx mcp-openapix

# Or run from source
npx -y @modelcontextprotocol/inspector@latest uv run mcp-openapix

Configuration

config.json MUST live at ~/.config/mcp-openapix/config.json (%USERPROFILE%\.config\… on Windows). config.example.json is a full template.

{
  "headers": { "accept": "application/json" },
  "defaults": { "platform": "example", "region": "us", "service": "items", "env": "prod" },
  "platforms": {
    "example": {
      "regions": {
        "us": {
          "services": {
            "token_helper": "us",
            "items": {
              "desc": "Catalogue and inventory API",
              "spec_path": "/swagger/v1/swagger.json",
              "canonical_env": "prod",
              "envs": {
                "prod": { "url": "https://api.example.com/items" },
                "dev":  { "url": "https://api-dev.example.com/items" }
              }
            }
          }
        }
      }
    }
  },
  "token_helpers": {
    "us": {
      "command": "token-helper",
      "args": ["issue"]
    }
  }
}

platforms

A hierarchy of platform → region → services → service → env. Each service declares:

The services object may also contain a token_helper default applying to all services in that region. A service or environment can override it.

token_helpers

Named token helpers, in the same shape as an MCP server entry:

The config names a command and nothing else, so config.json holds no secrets. The complete helper invocation and output contract is documented in docs/token-protocol.md.

Which helper a call uses is resolved most-specific-first:

Shortened. The full README is on GitHub.