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 list_platforms, list_endpoints and describe_endpoint; execution is the generic proxy call_endpoint.

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:

env.token_helper → service.token_helper → services.token_helper
→ region.token_helper → platform.token_helper → defaults.token_helper

If no level declares a helper, the deployment is unauthenticated. Omit token_helper for public deployments.

headers

Constant headers added to every API call — for APIs that require a tenant, product or locale header:

"headers": { "accept": "application/json", "x-product": "example" }

defaults

Makes every tool argument optional: a call falls back to defaults.platform, .region, .service, .env, .username and .token_helper when they are omitted.

Top-level options

Splitting the config

A stray comma while editing one platform takes down every platform: a parse failure precedes per-platform validation. The config MAY therefore be split into drop-in files under config.d/, in the style of an nginx conf.d. The recommended layout keeps server-wide settings in config.json and gives each platform its own file, named after it:

~/.config/mcp-openapix/
├── config.json      # defaults, headers, token_helpers, top-level options
└── config.d/
    ├── acme.json    # {"platforms": {"acme": …}}
    └── public.json  # {"platforms": {"public": …}}

A typo then costs one platform, and a platform can be handed over, or removed, as a single file. Token helpers stay in config.json because they are usually shared across platforms; a helper only one platform uses MAY live beside it in that platform's file.

The layout is a convention, not a rule:

• config.json is read first, then every *.json directly in config.d/ in sorted order. Subdirectories, .bak and editor swap files are ignored; no config.d/ means no change in behavior.
• A drop-in MAY declare anything config.json may, and config.json MAY be nearly empty.
• Files merge as if pasted into one config in that order: objects merge key by key, and a later scalar or list replaces the earlier one. A later file can therefore override a single envs.prod.url or one defaults field.

A file that fails to parse costs only what it declares; the rest keep working. A malformed platform, in any file, MUST NOT stop the others loading, and neither does a missing token helper it names: its error lists any files that were skipped, since the helper may be declared in one. list_platforms shows a platform that failed with no regions and the loader's error, and a skipped file as {"file", "error"}; calling into a failed platform returns the same message. Defaults that point into a failed platform are ignored. An invalid setting outside platforms still stops the server, and the message names the file that set it.

A fix needs a restart. Check the config first, without starting the server; it also lists every value a later file overrode:

uvx mcp-openapix --check-config

Tools

Operation ids

Many OpenAPI documents omit operationId, so the server synthesizes one as "<METHOD> <path>":

POST /api/items
└─┬─┘ └───┬───┘
method  path as the spec declares it

Where a spec does declare an operationId, that value wins.

Specs

Specs are not bundled. Each deployment's document is fetched on demand — an unauthenticated GET — and cached under ~/.cache/mcp-openapix/{platform}/{region}/{service}.json.

A document MUST declare at least one operation before it is installed, so a deployment answering 200 with an error body cannot replace a working snapshot with one that serves nothing.

Cached specs refresh in the background: once at startup, then every spec_refresh.interval days. Set auto to false to stop it; the manual lever still works:

uvx mcp-openapix --refresh

MCP resources

Both expire response_cache_ttl seconds after the call. The curl command may embed a short-lived token.

Tokens at rest

Tokens are cached in memory and, when expiry metadata is available, under ~/.cache/mcp-openapix/tokens/ (mode 0600) keyed by the token-helper declaration and username. This lets client sessions share a login without spawning a helper each. A 401 retires the cached token so the next call obtains a fresh one. To clear them all:

uvx mcp-openapix --logout

MCP host examples

{
  "mcpServers": {
    "openapi": { "command": "uvx", "args": ["mcp-openapix"] }
  }
}

[mcp_servers.openapi]
command = "uvx"
args = ["mcp-openapix"]

Development

uv sync --extra dev
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest

All four MUST pass; see AGENTS.md. Tests use respx to mock HTTP and real subprocesses for token helpers, so no live API access is required.

License

MIT.