English | Türkçe
Convierte cualquier API REST OpenAPI en un servidor MCP — para que Claude Code, Cursor y cualquier otro cliente MCP puedan llamar a tu API directamente.
mcpify es centrado, listo para producción y CLI-first: un solo trabajo (OpenAPI → MCP), una sola interfaz (un único comando sobre stdio), cero dependencias en tiempo de ejecución. Centrado no significa pequeño: 162 pruebas en once suites, compatibilidad dual con la especificación MCP, una capa de políticas, caché, reintentos seguros y sondas de salud respaldan ese único trabajo.
Tu empresa tiene una API REST. Tu agente de IA necesita llamarla. Hasta ahora eso significaba escribir a mano un servidor MCP personalizado para cada API. Con mcpify:
mcpify serve https://your-company.com/openapi.jsonEso es todo: cada endpoint se ha convertido en una herramienta que tu agente de IA puede descubrir, entender y llamar.
Documentación en profundidad: Guía de uso — patrones de autenticación, alcance, Docker, solución de problemas · Arquitectura · Contribuir · Registro de cambios · Seguridad
La historia del lanzamiento: Cómo una API meteorológica en vivo rompió esta herramienta — y la hizo mejor
60 segundos para que funcione — apúntalo a cualquier especificación OpenAPI 3.x (archivo o URL)
Las credenciales nunca tocan la especificación ni el modelo — se obtienen de tu
entorno en el momento de la llamada (--auth-env), se envían como Authorization: Bearer,
una cabecera personalizada o un parámetro de consulta
Cada operación se convierte en una herramienta MCP de primera clase — los esquemas de entrada se
generan a partir de parameters + requestBody, los $ref internos se resuelven
Acótalo — --read-only (solo GET), --tag payments,
--include /v1/orders, --exclude /admin, además de una capa de políticas para APIs del mundo real:
--deny REGEX oculta los GET mutantes, --allow REGEX vuelve a incluir
endpoints POST de tipo lectura. Deny siempre gana.
mcpify doctor — te dice si tu especificación es compatible con agentes antes de publicarla
Operativa, no solo funcional. Asistente mcpify init + configuraciones .mcpify.toml
con secciones por entorno, caché de respuestas GET (--cache-ttl),
reintentos seguros (--retry — solo métodos idempotentes, solo 502/503/504),
registro verboso/en archivo con credenciales enmascaradas, conversión XML→JSON,
modo de argumentos estricto, autodetección de origen, tolerancia a lotes heredados y
una sonda de salud (mcpify status / mcpify_health)
Cero dependencias en tiempo de ejecución — todo el árbol es stdlib de Python
auditable; las especificaciones YAML necesitan un pip install 'mcpify[yaml]' opcional
Superficie de nivel agente. Las anotaciones de herramientas se derivan de la semántica HTTP
(los clientes autoaprueban herramientas de solo lectura), salida estructurada mediante MCP
outputSchema/structuredContent, errores de nivel remediación que enseñan la
siguiente llamada, vistas previas de solicitudes en seco y un modo --lazy de buscar-y-llamar
que redujo el listado de api.weather.gov en un 95.5% (38,882 → 1,741 caracteres)
162 pruebas en once suites — incluida una ejecución completa del protocolo MCP sobre stdio contra una API HTTP local real y el documento en vivo de api.weather.gov (69 herramientas, 16 parámetros con enum)
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-onlyFlag | Significado |
| variable de entorno que contiene la credencial |
| cómo se envía |
| nombre de cabecera / consulta para estilos que no son bearer (p. ej. |
Claude Code:
claude mcp add my-api -- mcpify serve openapi.json --read-onlyClaude Desktop / Cursor / cualquier cliente MCP (claude_desktop_config.json):
{
"mcpServers": {
"petstore": {
"command": "mcpify",
"args": ["serve", "~/specs/petstore.json", "--auth-env", "PETSTORE_KEY"]
}
}
}Ahora pregúntale a tu agente: "lista las mascotas, luego crea una llamada Milo" — descubre list_pets y create_pet, rellena los argumentos y realiza llamadas HTTP reales.
OpenAPI | mcpify |
| nombre de la herramienta (saneado; recurre a |
| descripción de la herramienta que lee el agente |
| se muestra con |
| argumentos individuales tipados con enums |
| un argumento de objeto |
| resueltos en línea (components → esquemas reales) |
| URL base por defecto (anulación: |
El agente solo ve la lista de herramientas y las respuestas JSON de tu API — mcpify no añade middleware, no guarda nada en caché y no envía credenciales a ningún sitio excepto a tu 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>Las especificaciones JSON funcionan de serie; las especificaciones YAML necesitan pip install 'mcpify[yaml]'
Solo se resuelven los punteros $ref locales (combina primero los documentos externos — la mayoría de las herramientas lo hacen de todos modos)
Los cuerpos de solicitud se exponen como un único argumento de objeto body — predecible antes que ingenioso
Versiones de especificación: se aceptan raíces OpenAPI 3.x y Swagger 2.x; 3.x es la ruta feliz
mcpify se audita en cada lanzamiento contra una lista de verificación de 10 categorías de mejores prácticas de MCP y modos de fallo de producción publicados — no solo nuestros propios ejemplos:
Corpus de especificaciones hostiles (12/12): $ref circulares, subidas multipart,
esquemas allOf, variables de URL de servidor, URLs base relativas, respuestas
sobredimensionadas — cada escenario derivado de un fallo real documentado,
corregido y fijado con una prueba de regresión. Las fuentes incluyen el estudio
de arXiv sobre generación REST→MCP en 18 APIs reales.
Integración en vivo: la especificación real de api.weather.gov se carga en CI — el caso que encontró (y corrigió) nuestro último error de clase crash.
Ciclo de vida de MCP garantizado: las herramientas son inalcanzables hasta que el cliente
completa el handshake de initialize.
Controles de radio de explosión: modo de solo lectura, capa de políticas deny/allow,
truncamiento de respuestas de 40k caracteres, --timeout, credenciales nunca registradas.
Lista de verificación completa con estado por elemento: docs/AUDIT-CHECKLIST.md
162 aprobadas, más una prueba de integración en vivo que carga el documento real de
api.weather.gov (se omite automáticamente sin conexión). Cada suite se ejecuta en
Python 3.10–3.12 en Linux y Windows; ruff, mypy estricto y
CodeQL controlan cada push.
Suite | Pruebas | Qué fija |
Análisis y resolución de especificaciones | 13 | Carga de OpenAPI 3.x + YAML, cadenas |
Traducción de herramientas | 19 | nombrado de operationId con sufijos de colisión, esquemas de entrada, enums, manejo de body, derivación de anotaciones y esquemas de salida |
Superficie de agente | 31 | anotaciones derivadas de HTTP, contrato de salida estructurada, errores de remediación, búsqueda |
CLI | 15 | flags de |
Corpus hostil | 11 |
|
Ciclo de vida e higiene | 8 | handshake de initialize ( |
Protocolo de extremo a extremo | 9 | JSON-RPC real sobre stdio contra una API HTTP local en vivo, aserciones a nivel de wire |
Capa de políticas | 7 |
|
Parámetros | 4 | esquemas de parámetros resueltos contra la especificación completa — la clase de error de weather.gov (una prueba toca el documento en vivo) |
Operaciones y configuración | 41 | archivos de configuración + precedencia de env, asistente init, TTL y límites de caché, seguridad de reintentos, conversión XML, descubrimiento, procesamiento por lotes, estado/salud |
Compatibilidad de versión de protocolo | 5 | solicitudes |
Política ante fallos: cada error encontrado en el mundo real se convierte en una prueba de regresión fijada antes de que se publique la corrección — la suite solo crece.
Ejecútalo localmente:
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 — genera un script de servidor independiente y compartible
Limitación de velocidad por operación
Flujo OAuth2 de credenciales de cliente
MIT — consulta el archivo LICENSE para más detalles.
[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.
