mcp-openapi-proxy

Turns any OpenAPI 3.x spec into a lightweight MCP stdio navigator/executor. The server always exposes 3 MCP tools and uses

toolName

identifiers to refer to individual endpoints.

For exhaustive reference, see the repository

README.md

. This skill is the short operational guide for installing the binary, wiring it into an MCP client, and using the current tool contract correctly.

Always discover the actual registered tools first; never assume semantic tool names.

Install

bash

go install github.com/rendis/mcp-openapi-proxy/cmd/mcp-openapi-proxy@latest

Quick Start

bash

MCP_SPEC=./openapi.yaml \
MCP_BASE_URL=https://api.example.com \
MCP_AUTH_TOKEN=your-token \
mcp-openapi-proxy

MCP_BASE_URL

is optional when the OpenAPI spec resolves to a single absolute

server

Recommended setup flow:

Install
```
mcp-openapi-proxy
```
Configure your MCP client:
- Claude Code: create
```
.mcp.json
```
  from
  .mcp.json.example
- Codex global: run
```
codex mcp add ...
```
- Codex project-local: create
```
./.codex/config.toml
```
  manually

Choose auth:

Static token: add
```
MCP_AUTH_TOKEN
```

OIDC: add

MCP_OIDC_ISSUER

and

MCP_OIDC_CLIENT_ID

, then run one of:

```
mcp-openapi-proxy login
```
```
mcp-openapi-proxy login <mcp_name>
```

mcp-openapi-proxy login --mcp-config ./path/to/.mcp.json

mcp-openapi-proxy login --mcp-config ./path/to/.mcp.json --server <mcp_name>

mcp-openapi-proxy login --codex-server <name>

mcp-openapi-proxy login --codex-config ~/.codex/config.toml

mcp-openapi-proxy login --codex-config ~/.codex/config.toml --server <name>

Start the MCP client

Use

list_endpoints

describe_endpoint

, and

call_endpoint

When

login

is invoked with

.mcp.json

or Codex config support, it reads the selected server’s

env

from that config entry. Shell env still overrides the config file when both are present.

Plain

mcp-openapi-proxy login

stays env-first. When shell env is not enough, it falls back to:

```
./.mcp.json
```

~/.codex/config.toml

(or

$CODEX_HOME/config.toml

)

If the server name is omitted,

login

discovers eligible servers from the selected config file. It only considers direct

command

values that point to the

mcp-openapi-proxy

binary (plain name, full path, or

.exe

path). Wrapper commands such as

go

env

docker

, or shell scripts are ignored. If more than one eligible server exists,

login

prints the options and prompts you to choose one.

If the source spec comes from

swag init

, convert it before using the proxy.

swag init

emits Swagger 2.0, while

mcp-openapi-proxy

expects OpenAPI 3.x:

bash

swag init -g cmd/api/main.go
swagger2openapi ./docs/swagger.json -o ./docs/openapi.json
MCP_SPEC=./docs/openapi.json mcp-openapi-proxy

Configuration

Variable	Required	Default	Description
`MCP_SPEC`	Yes	—	Path or URL to OpenAPI 3.x spec (YAML/JSON)
`MCP_BASE_URL`	No	—	Explicit API base URL. If omitted, the proxy uses a single absolute OpenAPI server when available
`MCP_TOOL_PREFIX`	No	`api`	Prefix for the 3 MCP tools and endpoint `toolName` identifiers
`MCP_AUTH_PROFILE`	No	`MCP_TOOL_PREFIX` or `default`	Namespace for stored OIDC tokens
`MCP_AUTH_TOKEN`	No	—	Global bearer token fallback
`MCP_OIDC_ISSUER`	No	—	OIDC issuer URL
`MCP_OIDC_CLIENT_ID`	No	—	OIDC client ID
`MCP_OIDC_SCOPES`	No	Spec scopes or `openid profile email offline_access`	Override OIDC login scopes
`MCP_EXTRA_HEADERS`	No	—	Comma-separated `key:value` pairs for every request
`MCP_MAX_BODY_BYTES`	No	`10485760`	Maximum response body size to buffer and return
`MCP_ALLOW_INSECURE_HTTP`	No	`0`	Allow sending credentials over non-loopback `http://` URLs
`MCP_EXCLUDE_DEPRECATED`	No	`0`	Skip deprecated endpoints when generating tools

MCP Client Setup

Claude Code (

.mcp.json

)

Generic example:

json

{
  "mcpServers": {
    "my-api": {
      "command": "mcp-openapi-proxy",
      "env": {
        "MCP_SPEC": "./openapi.yaml",
        "MCP_BASE_URL": "https://api.example.com",
        "MCP_TOOL_PREFIX": "myapi",
        "MCP_AUTH_PROFILE": "myapi"
      }
    }
  }
}

Static token variant:

json

{
  "mcpServers": {
    "my-api": {
      "command": "mcp-openapi-proxy",
      "env": {
        "MCP_SPEC": "./openapi.yaml",
        "MCP_BASE_URL": "https://api.example.com",
        "MCP_TOOL_PREFIX": "myapi",
        "MCP_AUTH_PROFILE": "myapi",
        "MCP_AUTH_TOKEN": "your-token"
      }
    }
  }
}

OIDC variant:

json

{
  "mcpServers": {
    "my-api": {
      "command": "mcp-openapi-proxy",
      "env": {
        "MCP_SPEC": "./openapi.yaml",
        "MCP_BASE_URL": "https://api.example.com",
        "MCP_TOOL_PREFIX": "myapi",
        "MCP_AUTH_PROFILE": "myapi",
        "MCP_OIDC_ISSUER": "https://auth.example.com/realms/myrealm",
        "MCP_OIDC_CLIENT_ID": "my-client"
      }
    }
  }
}

OIDC login from

.mcp.json

bash

mcp-openapi-proxy login

Or select the server explicitly:

bash

mcp-openapi-proxy login my-api

Or with an explicit config path:

bash

mcp-openapi-proxy login --mcp-config ./path/to/.mcp.json

Or with an explicit config path plus explicit server:

bash

mcp-openapi-proxy login --mcp-config ./path/to/.mcp.json --server my-api

OpenAI Codex (

.codex/config.toml

)

Global install via Codex CLI:

bash

codex mcp add my-api \
  --env MCP_SPEC=./openapi.yaml \
  --env MCP_BASE_URL=https://api.example.com \
  --env MCP_TOOL_PREFIX=myapi \
  --env MCP_AUTH_TOKEN=your-token \
  -- mcp-openapi-proxy

OIDC variant via Codex CLI:

bash

codex mcp add my-api \
  --env MCP_SPEC=./openapi.yaml \
  --env MCP_BASE_URL=https://api.example.com \
  --env MCP_TOOL_PREFIX=myapi \
  --env MCP_AUTH_PROFILE=myapi \
  --env MCP_OIDC_ISSUER=https://auth.example.com/realms/myrealm \
  --env MCP_OIDC_CLIENT_ID=my-client \
  -- mcp-openapi-proxy

Global Codex installs go into

~/.codex/config.toml

Project-local Codex config is manual because the visible

codex mcp add

help does not expose a project-scoped install mode. Use

./.codex/config.toml

when you want repo-local configuration:

toml

[mcp_servers.my-api]
command = "mcp-openapi-proxy"

[mcp_servers.my-api.env]
MCP_SPEC = "./openapi.yaml"
MCP_BASE_URL = "https://api.example.com"
MCP_TOOL_PREFIX = "myapi"
MCP_AUTH_TOKEN = "your-token"

For this stdio server, use

mcp-openapi-proxy login

, not

codex mcp login

bash

mcp-openapi-proxy login --codex-server my-api
mcp-openapi-proxy login --codex-config ~/.codex/config.toml
mcp-openapi-proxy login --codex-config ~/.codex/config.toml --server my-api
mcp-openapi-proxy login --codex-config ./.codex/config.toml --server my-api

codex mcp login

is for OAuth that Codex manages itself. Here the proxy owns OIDC discovery, PKCE, and token storage.

If local

./.codex/config.toml

is ignored, switch to the global

~/.codex/config.toml

path or use a trusted project in Codex.

Gemini CLI (

~/.gemini/settings.json

)

json

{
  "mcpServers": {
    "my-api": {
      "command": "mcp-openapi-proxy",
      "env": {
        "MCP_SPEC": "./openapi.yaml",
        "MCP_BASE_URL": "https://api.example.com",
        "MCP_TOOL_PREFIX": "myapi",
        "MCP_AUTH_TOKEN": "your-token"
      }
    }
  }
}

Authentication

Credential resolution order is:

```
MCP_AUTH_<SCHEME>_*
```
global
```
MCP_AUTH_TOKEN
```
OIDC token cache for
```
MCP_AUTH_PROFILE
```

Static Token (dev/CI)

Set

MCP_AUTH_TOKEN

to provide a global bearer fallback for bearer-compatible schemes.

For Claude Code, the usual place is

.mcp.json -> mcpServers.<name>.env.MCP_AUTH_TOKEN

Per-Scheme Credentials

Use the OpenAPI security scheme name, uppercased and sanitized by replacing

, and spaces with underscores.

http bearer

oauth2

openIdConnect

→

MCP_AUTH_<SCHEME>_TOKEN

http basic

→

MCP_AUTH_<SCHEME>_USERNAME

and

MCP_AUTH_<SCHEME>_PASSWORD

```
apiKey
```
→
```
MCP_AUTH_<SCHEME>_KEY
```

Example:

bash

MCP_AUTH_PARTNER_AUTH_V2_TOKEN=secret-token
MCP_AUTH_ADMIN_BASIC_USERNAME=alice
MCP_AUTH_ADMIN_BASIC_PASSWORD=s3cr3t
MCP_AUTH_X_API_KEY_KEY=dev-key

OIDC PKCE (production)

Standard OIDC discovery (recommended):

bash

MCP_OIDC_ISSUER=https://auth.example.com/realms/myrealm \
MCP_OIDC_CLIENT_ID=my-client \
mcp-openapi-proxy login

If your MCP client uses

.mcp.json

or Codex TOML, these forms now read the selected server’s

env

automatically:

```
mcp-openapi-proxy login
```
```
mcp-openapi-proxy login my-api
```

mcp-openapi-proxy login --mcp-config ./path/to/.mcp.json

mcp-openapi-proxy login --mcp-config ./path/to/.mcp.json --server my-api

mcp-openapi-proxy login --codex-server my-api

mcp-openapi-proxy login --codex-config ~/.codex/config.toml

mcp-openapi-proxy login --codex-config ~/.codex/config.toml --server my-api

Keep the same

MCP_AUTH_PROFILE

MCP_OIDC_ISSUER

, and

MCP_OIDC_CLIENT_ID

values there so the running server uses the token cache created by

login

If the server name is omitted,

login

only considers direct

mcp-openapi-proxy

commands from the selected config file. Wrapper commands such as

go

env

docker

, or shell scripts are not eligible for login discovery. When multiple eligible entries exist,

login

lists them and prompts you to choose one.

If you also set those values in the shell when invoking

login

, the shell values win.

Application-specific discovery:

bash

MCP_BASE_URL=https://api.example.com mcp-openapi-proxy login

Commands:

```
mcp-openapi-proxy login
```
```
mcp-openapi-proxy status
```
```
mcp-openapi-proxy logout
```

Scopes come from

MCP_OIDC_SCOPES

when set. Otherwise, if

MCP_SPEC

is available, the proxy unions scopes from the OpenAPI security requirements. If neither source is available, it falls back to

openid profile email offline_access

Tokens are stored at

~/.mcp-openapi-proxy/<profile>-tokens.json

, where

<profile>

comes from

MCP_AUTH_PROFILE

or falls back to the tool prefix /

default

Registered Tools and Endpoint IDs

The MCP server always exposes exactly these tools:

```
{prefix}_list_endpoints
```
```
{prefix}_describe_endpoint
```
```
{prefix}_call_endpoint
```

Always inspect the registered tools first. Do not assume the server exposes one MCP tool per endpoint anymore.

Each OpenAPI endpoint still has a stable

toolName

text

{prefix}_{method}_{sanitized_path}

That

toolName

is the identifier you pass into

describe_endpoint

and

call_endpoint

Feature Flags API example with

MCP_TOOL_PREFIX=fe

Operation	Endpoint `toolName`
`GET /admin/features`	`fe_get_admin_features`
`POST /admin/features`	`fe_post_admin_features`
`GET /admin/features/{key}`	`fe_get_admin_features_key`
`PATCH /admin/features/{key}/toggle`	`fe_patch_admin_features_key_toggle`
`GET /admin/workspaces`	`fe_get_admin_workspaces`

Names like

fe_list_features

fe_toggle_feature

are not part of the product contract.

Input and Output Contract

Recommended agent flow:

Call
```
{prefix}_list_endpoints
```
Pick a
```
toolName
```
Call
```
{prefix}_describe_endpoint
```
if you need the exact contract
Call
```
{prefix}_call_endpoint
```

list_endpoints

Input:

json

{
  "q": "feature",
  "path_prefix": "/admin",
  "method": "PATCH",
  "auth": "bearer",
  "limit": 25
}

Output:

json

{
  "items": [
    {
      "toolName": "fe_patch_admin_features_key_toggle",
      "method": "PATCH",
      "path": "/admin/features/{key}/toggle",
      "description": "Toggle a feature flag",
      "requiredAuth": "bearer",
      "tags": ["flags", "admin"],
      "deprecated": false
    }
  ],
  "nextCursor": ""
}

describe_endpoint

Input:

json

{
  "toolName": "fe_patch_admin_features_key_toggle"
}

Output includes:

toolName

method

path

summary

description

deprecated

```
requiredAuth
```
and full
```
securityRequirements
```
```
parameters.path/query/headers/cookies
```
```
requestBody
```
with media types, schema, examples, and encoding
```
responses
```
with status, description, headers, and body schemas
```
externalDocs
```
,
```
servers
```
,
```
baseURLHint
```

call_endpoint

Input:

json

{
  "toolName": "fe_patch_admin_features_key_toggle",
  "path": {
    "key": "checkout"
  },
  "headers": {
    "X-Workspace": "acme"
  },
  "body": {
    "enabled": true
  }
}

X-Workspace

is sent in

headers

per request or configured globally with

MCP_EXTRA_HEADERS

. Workspace selection is header-based, not a dedicated tool.

call_endpoint

returns the HTTP envelope:

json

{
  "status": 200,
  "content_type": "application/json",
  "headers": {
    "X-Trace": ["abc123"]
  },
  "body": {
    "id": "item-1"
  }
}

API
```
4xx/5xx
```
responses preserve the real HTTP response and set
```
IsError=true
```
Proxy/runtime failures return
```
status: 0
```
plus
```
proxy_error
```
Binary payloads are represented as base64 wrappers
Deprecated endpoints are listed by default and only excluded with
```
MCP_EXCLUDE_DEPRECATED=1
```

Multiple APIs

Use distinct prefixes to run side-by-side:

json

{
  "mcpServers": {
    "users-api": { "command": "mcp-openapi-proxy", "env": { "MCP_TOOL_PREFIX": "users", "..." : "..." } },
    "billing-api": { "command": "mcp-openapi-proxy", "env": { "MCP_TOOL_PREFIX": "billing", "..." : "..." } }
  }
}

Common Mistakes

Missing
MCP_SPEC
→ startup fails immediately
No usable base URL → set
```
MCP_BASE_URL
```
explicitly or declare a single absolute OpenAPI
```
server
```
Spec generated by
swag init
→ detect
```
swagger: "2.0"
```
or a generated
```
swagger.json
```
, convert it with
```
swagger2openapi
```
, then point
```
MCP_SPEC
```
at the resulting OpenAPI 3.x file

Missing per-scheme auth → configure

MCP_AUTH_<SCHEME>_*

MCP_AUTH_TOKEN

, or run

mcp-openapi-proxy login

Spec URL unreachable → fails at startup; check network/VPN
Authenticated calls to non-loopback
http://
→ blocked unless
```
MCP_ALLOW_INSECURE_HTTP=1
```
Treating endpoints as MCP tools → endpoints are discovered as
```
toolName
```
values; only
```
list_endpoints
```
,
```
describe_endpoint
```
, and
```
call_endpoint
```
are registered
Calling
call_endpoint
without discovery → list first, then describe if needed, then call with
```
toolName
```

For exhaustive reference, examples, and troubleshooting, see the repository

README.md

mcp-openapi-proxy

NPX Install

Tags

SKILL.md Content

mcp-openapi-proxy

Install

Quick Start

Configuration

MCP Client Setup

Claude Code (
`.mcp.json`
)

OpenAI Codex (
`.codex/config.toml`
)

Gemini CLI (
`~/.gemini/settings.json`
)

Authentication

Static Token (dev/CI)

Per-Scheme Credentials

OIDC PKCE (production)

Registered Tools and Endpoint IDs

Input and Output Contract

`list_endpoints`

`describe_endpoint`

`call_endpoint`

Multiple APIs

Common Mistakes

mcp-openapi-proxy

NPX Install

Tags

SKILL.md Content

mcp-openapi-proxy

Install

Quick Start

Configuration

MCP Client Setup

Claude Code (.mcp.json)

OpenAI Codex (.codex/config.toml)

Gemini CLI (~/.gemini/settings.json)

Authentication

Static Token (dev/CI)

Per-Scheme Credentials

OIDC PKCE (production)

Registered Tools and Endpoint IDs

Input and Output Contract

list_endpoints

describe_endpoint

call_endpoint

Multiple APIs

Common Mistakes

Claude Code (
`.mcp.json`
)

OpenAI Codex (
`.codex/config.toml`
)

Gemini CLI (
`~/.gemini/settings.json`
)

`list_endpoints`

`describe_endpoint`

`call_endpoint`