mcp-openapi-proxy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

可将任意OpenAPI 3.x规范转换为轻量级的MCP stdio导航/执行器。该服务器始终暴露3个MCP工具，并使用

toolName

标识符来指代各个端点。

如需完整参考，请查看代码仓库的

README.md

。本skill是安装二进制文件、将其接入MCP客户端、正确使用当前工具契约的精简操作指南。

请务必先发现实际注册的工具，切勿假设工具名称的语义。

Install

安装

bash

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

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

bash

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

当OpenAPI规范解析后仅包含单个绝对

server

地址时，

MCP_BASE_URL

为可选配置。

推荐设置流程：

安装
```
mcp-openapi-proxy
```
配置你的MCP客户端：
- Claude Code：参考
```
.mcp.json.example
```
  创建
```
.mcp.json
```
- Codex全局配置：执行
```
codex mcp add ...
```
- Codex项目本地配置：手动创建
```
./.codex/config.toml
```

选择身份验证方式：

静态令牌：添加
```
MCP_AUTH_TOKEN
```

OIDC：添加

MCP_OIDC_ISSUER

和

MCP_OIDC_CLIENT_ID

，然后执行以下任意命令：

```
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>

启动MCP客户端

使用

list_endpoints

、

describe_endpoint

和

call_endpoint

当调用

login

时如果指定了

.mcp.json

或Codex配置支持，它会从对应配置项中读取所选服务器的

env

配置。当两者同时存在时，Shell环境变量会覆盖配置文件中的值。

单纯执行

mcp-openapi-proxy login

会优先使用环境变量。当Shell环境变量不足时，会按以下顺序 fallback：

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

~/.codex/config.toml

（或

$CODEX_HOME/config.toml

）

如果省略服务器名称，

login

会从选中的配置文件中发现符合条件的服务器。它只会识别指向

mcp-openapi-proxy

二进制文件的直接

command

值（纯名称、完整路径或

.exe

路径）。诸如

go

、

env

、

docker

或Shell脚本之类的包装命令会被忽略。如果存在多个符合条件的服务器，

login

会打印选项并提示你选择一个。

如果源规范来自

swag init

，请在使用代理前先转换格式。

swag init

生成的是Swagger 2.0格式，而

mcp-openapi-proxy

需要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_SPEC`	是	—	OpenAPI 3.x规范的路径或URL（支持YAML/JSON格式）
`MCP_BASE_URL`	否	—	显式指定API基础URL。如果省略，代理会优先使用OpenAPI规范中提供的单个绝对服务地址
`MCP_TOOL_PREFIX`	否	`api`	3个MCP工具和端点 `toolName` 标识符的前缀
`MCP_AUTH_PROFILE`	否	`MCP_TOOL_PREFIX` 的值或 `default`	存储OIDC令牌的命名空间
`MCP_AUTH_TOKEN`	否	—	全局Bearer令牌兜底配置
`MCP_OIDC_ISSUER`	否	—	OIDC issuer地址
`MCP_OIDC_CLIENT_ID`	否	—	OIDC客户端ID
`MCP_OIDC_SCOPES`	否	规范中定义的scope或 `openid profile email offline_access`	覆盖OIDC登录的scope
`MCP_EXTRA_HEADERS`	否	—	每个请求都会携带的额外请求头，格式为逗号分隔的 `key:value` 对
`MCP_MAX_BODY_BYTES`	否	`10485760`	可缓冲返回的最大响应体大小
`MCP_ALLOW_INSECURE_HTTP`	否	`0`	允许通过非回环 `http://` URL发送凭证
`MCP_EXCLUDE_DEPRECATED`	否	`0`	生成工具时跳过已废弃的端点

MCP Client Setup

MCP客户端设置

Claude Code (

.mcp.json

)

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

通用示例：

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"
      }
    }
  }
}

静态令牌配置示例：

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配置示例：

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"
      }
    }
  }
}

从

.mcp.json

读取配置执行OIDC登录：

bash

mcp-openapi-proxy login

或显式选择服务器：

bash

mcp-openapi-proxy login my-api

或指定配置文件路径：

bash

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

或同时指定配置文件路径和服务器：

bash

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

OpenAI Codex (

.codex/config.toml

)

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.

通过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

通过Codex CLI安装的OIDC版本：

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

Codex全局配置会存入

~/.codex/config.toml

。

Codex项目本地配置需要手动设置，因为当前

codex mcp add

的帮助信息中没有暴露项目范围的安装模式。如果你需要仓库本地配置，请使用

./.codex/config.toml

：

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"

对于这个stdio服务器，请使用

mcp-openapi-proxy login

而非

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

适用于Codex自行管理的OAuth场景。而本代理自行负责OIDC发现、PKCE和令牌存储。

如果本地

./.codex/config.toml

被忽略，请切换到全局

~/.codex/config.toml

路径，或在Codex中使用受信任的项目。

Gemini CLI (

~/.gemini/settings.json

)

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"
      }
    }
  }
}

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
```

凭证解析顺序为：

```
MCP_AUTH_<SCHEME>_*
```
全局
```
MCP_AUTH_TOKEN
```
```
MCP_AUTH_PROFILE
```
对应的OIDC令牌缓存

Static Token (dev/CI)

静态令牌（开发/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

设置

MCP_AUTH_TOKEN

可以为兼容Bearer的认证方案提供全局Bearer兜底配置。

对于Claude Code，通常配置在

.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

使用OpenAPI安全方案的名称，将其转为大写，并将

、

和空格替换为下划线后使用。

http bearer

、

oauth2

、

openIdConnect

→

MCP_AUTH_<SCHEME>_TOKEN

http basic

→

MCP_AUTH_<SCHEME>_USERNAME

和

MCP_AUTH_<SCHEME>_PASSWORD

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

示例：

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)

OIDC PKCE（生产环境）

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

标准OIDC发现（推荐）：

bash

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

如果你的MCP客户端使用

.mcp.json

或Codex TOML配置，以下命令现在可以自动读取所选服务器的

env

配置：

```
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

请保持配置中

MCP_AUTH_PROFILE

、

MCP_OIDC_ISSUER

和

MCP_OIDC_CLIENT_ID

的值一致，这样运行中的服务器可以使用

login

命令创建的令牌缓存。

如果省略服务器名称，

login

只会识别选中的配置文件中直接调用

mcp-openapi-proxy

的命令。诸如

go

、

env

、

docker

或Shell脚本之类的包装命令不符合登录发现的条件。当存在多个符合条件的条目时，

login

会列出所有选项并提示你选择一个。

如果你在调用

login

时同时在Shell中设置了这些值，Shell中的值优先级更高。

应用专属发现：

bash

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

Registered Tools and Endpoint IDs

注册工具与端点ID

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.

MCP服务器始终只会暴露以下3个工具：

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

请务必先检查注册的工具。不要再假设服务器会为每个端点暴露单独的MCP工具。

每个OpenAPI端点仍然有稳定的

toolName

：

text

{prefix}_{method}_{sanitized_path}

toolName

是你传入

describe_endpoint

和

call_endpoint

的标识符。

功能开关API示例，

MCP_TOOL_PREFIX=fe

：

操作	端点 `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`

诸如

fe_list_features

或

fe_toggle_feature

之类的名称不属于产品契约的一部分。

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
```

推荐的Agent流程：

调用
```
{prefix}_list_endpoints
```
选择一个
```
toolName
```
如果需要确切的契约，调用
```
{prefix}_describe_endpoint
```
调用
```
{prefix}_call_endpoint
```

list_endpoints

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": ""
}

输入：

json

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

输出：

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

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
```

输入：

json

{
  "toolName": "fe_patch_admin_features_key_toggle"
}

输出包含：

toolName

、

method

、

path

、

summary

、

description

、

deprecated

```
requiredAuth
```
和完整的
```
securityRequirements
```
```
parameters.path/query/headers/cookies
```
包含媒体类型、schema、示例和编码的
```
requestBody
```
包含状态码、描述、请求头和响应体schema的
```
responses
```
```
externalDocs
```
、
```
servers
```
、
```
baseURLHint
```

call_endpoint

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
```

输入：

json

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

X-Workspace

可以按请求在

headers

中传递，或通过

MCP_EXTRA_HEADERS

全局配置。工作区选择基于请求头实现，没有单独的工具。

call_endpoint

返回HTTP信封：

json

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

API的
```
4xx/5xx
```
响应会保留真实的HTTP响应，并设置
```
IsError=true
```
代理/运行时错误会返回
```
status: 0
```
以及
```
proxy_error
```
二进制 payload 会以base64包装的形式呈现
默认会列出已废弃的端点，仅当设置
```
MCP_EXCLUDE_DEPRECATED=1
```
时才会排除

Multiple APIs

多API支持

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", "..." : "..." } }
  }
}

使用不同的前缀即可并行运行多个代理：

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_SPEC
配置 → 启动会立即失败
无可用的基础URL → 显式设置
```
MCP_BASE_URL
```
，或在OpenAPI规范中声明单个绝对
```
server
```
地址
规范由
swag init
生成 → 检测到
```
swagger: "2.0"
```
或生成的
```
swagger.json
```
时，使用
```
swagger2openapi
```
转换格式，然后将
```
MCP_SPEC
```
指向生成的OpenAPI 3.x文件
缺少按认证方案的身份验证配置 → 配置
```
MCP_AUTH_<SCHEME>_*
```
、
```
MCP_AUTH_TOKEN
```
，或执行
```
mcp-openapi-proxy login
```
规范URL无法访问 → 启动失败，请检查网络/VPN
向非回环
http://
地址发起认证请求 → 默认被拦截，除非设置
```
MCP_ALLOW_INSECURE_HTTP=1
```
将端点视为MCP工具 → 端点以
```
toolName
```
值的形式被发现，仅
```
list_endpoints
```
、
```
describe_endpoint
```
和
```
call_endpoint
```
是注册的工具
未经过发现就调用
call_endpoint
→ 先列出端点，必要时查询详情，然后使用
```
toolName
```
调用

如需完整参考、示例和问题排查，请查看代码仓库的

README.md

。

mcp-openapi-proxy

Original

Translation

mcp-openapi-proxy

mcp-openapi-proxy

Install

安装

Quick Start

快速开始

Configuration

配置

MCP Client Setup

MCP客户端设置

Claude Code (.mcp.json)

Claude Code (.mcp.json)

OpenAI Codex (.codex/config.toml)

OpenAI Codex (.codex/config.toml)

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

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

Authentication

身份验证

Static Token (dev/CI)

静态令牌（开发/CI场景）

Per-Scheme Credentials

按认证方案配置凭证

OIDC PKCE (production)

OIDC PKCE（生产环境）

Registered Tools and Endpoint IDs

注册工具与端点ID

Input and Output Contract

输入输出契约

list_endpoints

list_endpoints

describe_endpoint

describe_endpoint

call_endpoint

call_endpoint

Multiple APIs

多API支持

Common Mistakes

常见问题

Claude Code (
`.mcp.json`
)

Claude Code (
`.mcp.json`
)

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

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

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

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

`list_endpoints`

`list_endpoints`

`describe_endpoint`

`describe_endpoint`

`call_endpoint`

`call_endpoint`