English | Türkçe
将任何 OpenAPI REST API 变成 MCP 服务器 —— 让 Claude Code、Cursor 以及所有其他 MCP 客户端都能直接调用你的 API。
mcpify 专注、生产就绪、CLI 优先：一项任务（OpenAPI → MCP）、一个接口（通过 stdio 的单一命令）、零运行时依赖。专注并不意味着小 —— 11 个测试套件中的 162 项测试、双 MCP 规范兼容、策略层、缓存、安全重试和健康探测，共同支撑起这一项任务。
你的公司有一个 REST API。你的 AI 代理需要调用它。在此之前，这意味着要为每个 API 手写一个自定义的 MCP 服务器。而使用 mcpify：
mcpify serve https://your-company.com/openapi.json就是这样 —— 每个端点都变成了你的 AI 代理可以发现、理解并调用的工具。
深度文档： 使用指南 —— 认证模式、范围控制、Docker、故障排查 · 架构 · 贡献指南 · 更新日志 · 安全
发布故事： 一个实时天气 API 如何让这个工具出错 —— 并让它变得更好
60 秒即可上手 —— 指向任何 OpenAPI 3.x 规范（文件或 URL）
凭据从不接触规范或模型 —— 在调用时从你的环境中获取（--auth-env），以 Authorization: Bearer、自定义请求头或查询参数的形式发送
每个操作都成为一等 MCP 工具 —— 输入模式由 parameters + requestBody 生成，内部 $ref 会被解析
缩小范围 —— --read-only（仅 GET）、--tag payments、--include /v1/orders、--exclude /admin，再加上适用于真实世界 API 的策略层：--deny REGEX 隐藏有副作用的 GET，--allow REGEX 重新包含读取风格的 POST 端点。Deny 始终优先。
mcpify doctor —— 在你发布之前告诉你规范是否对代理友好
运营就绪，而不仅仅是功能可用。 mcpify init 向导 + 带分环境小节的 .mcpify.toml 配置、GET 响应缓存（--cache-ttl）、安全重试（--retry —— 仅幂等方法，仅 502/503/504）、带凭据脱敏的详细/日志文件记录、XML→JSON 转换、严格参数模式、来源自动发现、旧版批量请求容忍，以及健康探测（mcpify status / mcpify_health）
零运行时依赖 —— 整个依赖树都是可审计的 Python 标准库；YAML 规范需要可选的 pip install 'mcpify[yaml]'
代理级接口。 工具注解来源于 HTTP 语义（客户端自动批准只读工具）、通过 MCP outputSchema/structuredContent 实现结构化输出、能指导下一次调用的修复级错误、预演请求预览，以及 --lazy 先搜索后调用模式 —— 该模式将 api.weather.gov 的列表缩减了 95.5%（38,882 → 1,741 个字符）
11 个测试套件共 162 项测试 —— 包括通过 stdio 对真实本地 HTTP API 的完整 MCP 协议运行，以及实时 api.weather.gov 文档（69 个工具，16 个枚举参数）
Related MCP server: @spec2tools/stdio-mcp
# run without installing (uvx — pulls from PyPI on demand)
uvx --from mcpify-openapi mcpify list ./openapi.json --read-only
# first time? the wizard writes a config for you
uvx --from mcpify-openapi mcpify init
# or install (installs the `mcpify` command)
pipx install mcpify-openapi
# ...as a container (GHCR, published on every release)
docker run -i ghcr.io/furkan708/mcpify:latest serve ./openapi.json --read-only
# ...or from source
git clone https://github.com/furkan708/mcpify.git
cd mcpify && pip install .
# 1. preview the tools that will be generated
mcpify list examples/petstore.json
# 2. validate the spec is agent-friendly
mcpify doctor examples/petstore.json
# 3. serve it over MCP
mcpify serve examples/petstore.json --base-url https://petstore.example.com/v1# Bearer token read from the environment (never hardcoded)
export PETSTORE_KEY="sk-..."
mcpify serve petstore.json \
--base-url https://petstore.example.com/v1 \
--auth-env PETSTORE_KEY \
--auth-style bearer \
--read-only标志 | 含义 |
| 保存凭据的环境变量 |
| 发送方式 |
| 非 Bearer 样式的请求头/查询参数名（例如 |
Claude Code:
claude mcp add my-api -- mcpify serve openapi.json --read-onlyClaude Desktop / Cursor / 任何 MCP 客户端（claude_desktop_config.json）：
{
"mcpServers": {
"petstore": {
"command": "mcpify",
"args": ["serve", "~/specs/petstore.json", "--auth-env", "PETSTORE_KEY"]
}
}
}现在对你的代理说：“列出宠物，然后创建一个名为 Milo 的宠物” —— 它会发现 list_pets 和 create_pet，填写参数，并执行真实的 HTTP 调用。
OpenAPI | mcpify |
| 工具名称（经过清理；回退到 |
| 代理读取的工具描述 |
| 在暴露旧端点之前由 |
| 带枚举的独立类型化参数 |
| 一个 |
| 就地解析（components → 真实模式） |
| 默认基础 URL（覆盖： |
代理只会看到工具列表和你 API 的 JSON 响应 —— mcpify 不会添加中间件，不会缓存任何内容，也不会将凭据发送到你的 API 之外的任何地方。
$ mcpify doctor my-api.json
openapi: 3.0.3
title: Acme API
paths: 23
tools: 41 operations
servers: https://api.acme.com
warning: 12/41 operations have no operationId (names fall back to method_path)
warning: 30/41 operations have no summary (agents see no description)mcpify list <spec> [--tag T] [--include P] [--exclude P] [--read-only] [--json]
mcpify serve <spec> [--base-url URL] [--name N] [--auth-env VAR]
[--auth-style bearer|header|query] [--auth-name NAME]
[--timeout S] [--read-only] [--tag T] [--include P] [--exclude P]
mcpify doctor <spec>JSON 规范开箱即用；YAML 规范需要 pip install 'mcpify[yaml]'
只解析本地 $ref 指针（请先捆绑外部文档 —— 大多数工具本来就会这样做）
请求体以单个 body 对象参数暴露 —— 可预测优于巧妙
规范版本：接受 OpenAPI 3.x 和 Swagger 2.x 根；3.x 是最佳路径
mcpify 在每次发布时都会对照 MCP 最佳实践的 10 类清单以及已公开的生产故障模式进行审计 —— 而不仅仅是我们的自有示例：
恶意规范语料库（12/12）： 循环 $ref、多部分上传、allOf 模式、服务器 URL 变量、相对基础 URL、超大响应 —— 每个场景都源自一个有记录的真实世界故障，经过修复并由回归测试锁定。来源包括 arXiv 上关于覆盖 18 个真实 API 的 REST→MCP 生成研究。
实时集成： 真实的 api.weather.gov 规范会在 CI 中加载 —— 正是这个案例发现（并修复）了我们最后一个崩溃级 bug。
强制 MCP 生命周期： 在客户端完成 initialize 握手之前，工具不可达。
爆炸半径控制： 只读模式、deny/allow 策略层、40k 字符响应截断、--timeout，凭据永不记录日志。
包含每项状态的完整清单：docs/AUDIT-CHECKLIST.md
162 项通过，外加一个加载真实 api.weather.gov 文档的实时集成测试（离线时自动跳过）。每个套件都在 Linux 和 Windows 上的 Python 3.10–3.12 上运行；ruff、严格 mypy 和 CodeQL 为每次推送把关。
测试套件 | 测试数 | 验证内容 |
规范解析与引用解析 | 13 | OpenAPI 3.x + YAML 加载、 |
工具转换 | 19 | operationId 命名与冲突后缀、输入模式、枚举、body 处理、注解与输出模式推导 |
代理接口 | 31 | 源自 HTTP 的注解、结构化输出契约、修复级错误、 |
CLI | 15 |
|
恶意语料库 | 11 | 循环 |
生命周期与卫生 | 8 |
|
协议端到端 | 9 | 通过 stdio 对真实本地 HTTP API 的实际 JSON-RPC、线级断言 |
策略层 | 7 |
|
| 4 | 参数模式针对完整规范解析 —— weather.gov bug 类型（一个测试命中实时文档） |
运维与配置 | 41 | 配置文件 + 环境变量优先级、init 向导、缓存 TTL 与边界、重试安全性、XML 转换、发现、批处理、状态/健康 |
协议版本兼容 | 5 | 同一链路上的 2026-07-28 无状态 |
故障处理策略：每个在实际环境中发现的 bug 都会在修复发布前成为一个固定的回归测试 —— 测试套件只会增长。
本地运行：
pip install pytest pyyaml
pytest -vmcpify/
├── mcpify/
│ ├── spec.py # OpenAPI loading, $ref resolution, operation walking
│ ├── tools.py # operation -> MCP tool, argument -> HTTP request
│ ├── http_client.py # execution (urllib, HTTP errors become tool results)
│ ├── api_server.py # MCP stdio server (JSON-RPC 2.0)
│ └── cli.py # list / serve / doctor
├── examples/petstore.json
└── tests/--output-server FILE —— 生成一个独立的、可共享的服务器脚本
按操作限流
OAuth2 客户端凭据流程
MIT —— 详细信息请参阅 LICENSE 文件。
[GET] Get a single pet
| Name | Required | Description | Default |
|---|---|---|---|
| petId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds only '[GET]', which mostly duplicates the safety information already provided by annotations such as readOnlyHint=true, idempotentHint=true, and destructiveHint=false. It does not disclose additional behavioral details like missing-ID handling, authentication requirements, rate limits, or response shape; the annotations do the heavy lifting.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant elaboration. For a simple one-parameter read operation, this is appropriately compact and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only get operation, the description plus annotations may be minimally sufficient, but the agent is left to infer too much from the tool name and parameter name. Missing guidance on what petId represents, how to handle nonexistent pets, and what a successful response looks like keeps this from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole required parameter petId has an empty schema description (0% coverage), and the tool description does not explain that petId identifies which pet to fetch or how it should be interpreted. The parameter name is suggestive, but the description adds no semantic value beyond what the schema already exposes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('a single pet'), which unambiguously conveys the operation and distinguishes it from list_pets by emphasizing singular retrieval. It does not explicitly contrast with siblings or mention the petId parameter, but the core purpose is clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'single' implies this tool is for retrieving one specific pet rather than listing pets or vaccinations, so usage context is indirectly suggested. However, there is no explicit statement of when to use this tool versus list_pets, no prerequisites, and no mention of alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[GET] Store statistics
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already convey readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds no behavioral context beyond the redundant "[GET]" marker, such as whether results are aggregated, paginated, or time-bound.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Although the description is short, it is under-specified rather than usefully concise. It only repeats the title and adds an HTTP-verb hint that is already available in the annotations, so the brevity buys the agent no added insight.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no clarification of what "statistics" means, the description is incomplete for an agent deciding whether this tool meets a user's request. It also fails to clarify how this endpoint relates to the sibling pet/vaccination tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the input schema is an empty object with no required fields. There is no parameter burden for the description to carry, so the baseline of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description "[GET] Store statistics" restates the tool title and name almost verbatim. It identifies the resource at a high level but does not specify what statistics are included, so an agent cannot tell whether this returns sales totals, visit counts, or something else.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use get_stats instead of list_pets, get_pet, list_vaccinations, or mcpify_health. There is no mention of typical use cases, exclusions, or alternatives, so the agent must guess based on the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[GET] List all pets
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | Filter by kind | |
| limit | No | How many pets to return |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description adds only the '[GET]' method and list scope. It does't disclose pagination/default limit/response shape or filtering behavior, so contextual transparency is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One short sentence with no filler, method prefix ('[GET]') front-loaded. Every token earns its place; it is appropriately sized for a simple list endpoint.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list with two optional params and no output schema, the description is mostly sufficient to invoke it. However, it leaves ambiguity about whether 'all' is exhaustive or paginated, and gives no hint of the return shape – a real but minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and both parameters already have meaningful descriptions ('Filter by kind', 'How many pets to return'). The description adds nothing beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all pets'), making the operation clear. It distinguishes from sibling get_pet (singular object vs. collection) and other siblings by resource/scope, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative routing. The word 'all' implies collection-level fetching, and siblings like get_pet imply single-item lookup, but the description leaves the choice to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[GET] List vaccinations of a pet
| Name | Required | Description | Default |
|---|---|---|---|
| petId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructveHint=false. The description adds only '[GET]', which mostly duplicates the read-only annotation, and provides no additional behavioral context such as empty results, 404 behavior, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundant elaboration. It is front-loaded and easy to parse, though extremely minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter read-only endpoint with rich annotations, a short description can be sufficient. However, it omits any mention of response shape, parameter semantics, or conditions for use, making it only minimally complete for guiding a correct call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the only parameter petId, and the description does not explicitly map 'petId' to its role beyond saying 'of a pet'. This gives a weak hint that petId identifies the pet but does not compensate for the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('List') and resource ('vaccinations of a pet'), which clearly distinguishes it from siblings like list_pets and get_pet. No ambiguity about what operation this tool performs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'of a pet' implies the tool is for retrieving vaccination records for one pet, but it does not explicitly state when to use it over alternatives or mention any exclusions. Usage is implied rather than directly guided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check that the upstream API is reachable and report this server's own configuration (tool count, cache, retry, auth).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a safe, read-only, idempotent operation. The description adds valuable context beyond annotations by disclosing that the tool reaches out to the upstream API and reports specific configuration details (tool count, cache, retry, auth). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no filler, and the main purpose is front-loaded before the specific reported fields. Every part of the sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, no parameters, and strong annotations, the description sufficiently covers what the tool does and what it reports. It could specify the response format, but for a health-check tool with no inputs this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, there is nothing for the description to clarify about inputs. The baseline of 4 applies since the schema is trivially complete and no param-level guidance is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Check' and names the exact resources: upstream API reachability and the server's own configuration. It clearly differentiates this health/config tool from the data-oriented siblings like list_pets and get_stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this when you need to verify upstream connectivity or inspect server configuration. It does not explicitly mention exclusions or when to prefer a sibling, but the described purpose strongly implies the appropriate usage scenario.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_petget_statslist_petslist_vaccinationsmcpify_healthScored across 5 tools
The four data tools are mostly distinct: list_pets/get_pet follow a standard list/detail pattern, and list_vaccinations clearly targets a subresource. get_stats and mcpify_health are also separate, though get_stats is vague enough that an agent might briefly confuse it with a health/status report.
list_pets, get_pet, list_vaccinations, and get_stats all use the snake_case verb_noun pattern. mcpify_health breaks that pattern structurally, and get_stats is less descriptive than a name like get_store_statistics would be.
Five tools is a compact, well-scoped set for this server. Each tool covers a distinct function: pet collection, pet detail, vaccination lookup, statistics, and health/configuration.
The read-oriented workflow is covered: list pets, get a specific pet, list vaccinations, retrieve stats, and check health. However, there are no create/update/delete tools for pets or vaccinations, which is a notable lifecycle gap unless the server is intentionally read-only.
Point Gecko at an OpenAPI spec; get first-call-correct, auth-hidden agent tools.
Generate a typed SDK, CLI, and MCP server from any OpenAPI or GraphQL spec, and keep them current.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Build, validate, deploy — HTTP APIs, cron jobs, webhooks and MCP tools — from your AI client.
