How do I install OpenAPI Services?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does OpenAPI Services need an API key?

No required environment variable is listed on this record.

What transport does OpenAPI Services use?

OpenAPI Services runs locally over stdio.

When was OpenAPI Services last checked?

Last checked 2026-11-09. MCP server that fronts any OpenAPI service: discover operations from its spec and call them

OpenAPI Services MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx mcp-openapix==0.2.1

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.alyiox-mcp-openapix -- uvx mcp-openapix==0.2.1

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.alyiox-mcp-openapix": {4      "command": "uvx",5      "args": [6        "mcp-openapix==0.2.1"7      ]8    }9  }10}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.2.1
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

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:

Field	Notes
`spec_path`	Required. The OpenAPI JSON endpoint relative to the service URL
`canonical_env`	Required when more than one env is configured — the env whose URL the spec is fetched from
`envs`	Required. One entry per deployment environment, each carrying a full base `url`
`desc`	Optional. A short description surfaced by `list_platforms`
`token_helper`	Optional. The token helper this level binds to

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:

Field	Required	Default	Notes
`command`	yes	—	Resolved on `PATH`; never run through a shell
`args`	no	`[]`	Passed verbatim
`timeout`	no	`60`	Seconds before the helper's process group is killed; at most `300`

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

Field	Default	Notes
`truncate_threshold`	`4096`	Response bytes returned inline before truncating to a preview
`response_cache_ttl`	`3600`	Seconds a truncated body stays readable at its resource URI
`spec_refresh`	`{"auto": true, "interval": 7}`	Background spec refresh; `interval` is days and MAY be fractional

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

Tool	Purpose
`list_platforms`	Every platform with its regions, services, and envs
`list_endpoints`	A service's operations, filtered by `query`, `tag` or `method`
`describe_endpoint`	One operation plus the transitive closure of the schemas it references
`call_endpoint`	Execute an operation, or a raw `method` + `path` absent from the spec

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

Resource URI	Description
`openapi://responses/{request_id}`	Full body of a truncated `call_endpoint` response
`openapi://curl/{request_id}`	Equivalent curl command for a `call_endpoint` request

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.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install OpenAPI Services?

Does OpenAPI Services need an API key?

What transport does OpenAPI Services use?

When was OpenAPI Services last checked?

Documentation

mcp-openapix

Requirements

Quick start

Configuration

platforms

token_helpers

headers

defaults

Top-level options

Splitting the config

Tools

Operation ids

Specs

MCP resources

Tokens at rest

MCP host examples

Development

License

`platforms`

`token_helpers`

`headers`

`defaults`