English | Türkçe
Verwandeln Sie jede OpenAPI-REST-API in einen MCP-Server — damit Claude Code, Cursor und jeder andere MCP-Client Ihre API direkt aufrufen können.
mcpify ist fokussiert, produktionsreif und CLI-first: eine Aufgabe (OpenAPI → MCP), eine Schnittstelle (ein einziger Befehl über stdio), null Laufzeitabhängigkeiten. Fokussiert bedeutet nicht klein — 162 Tests in elf Suiten, duale MCP-Spezifikationskompatibilität, eine Policy-Ebene, Caching, sichere Wiederholungsversuche und Health-Checks untermauern diese eine Aufgabe.
Ihr Unternehmen hat eine REST-API. Ihr KI-Agent muss sie aufrufen. Bisher bedeutete das, für jede API einen eigenen MCP-Server von Hand zu schreiben. Mit mcpify:
mcpify serve https://your-company.com/openapi.jsonDas war's — jeder Endpunkt ist jetzt ein Tool, das Ihr KI-Agent entdecken, verstehen und aufrufen kann.
Ausführliche Dokumentation: Nutzungsanleitung — Authentifizierungsmuster, Scoping, Docker, Fehlerbehebung · Architektur · Mitwirken · Changelog · Sicherheit
Die Entstehungsgeschichte: Wie eine Live-Wetter-API dieses Tool kaputt machte — und es besser machte
In 60 Sekunden einsatzbereit — richten Sie es auf eine beliebige OpenAPI-3.x-Spezifikation (Datei oder URL)
Anmeldedaten berühren weder die Spezifikation noch das Modell — sie werden zur Aufrufzeit aus Ihrer Umgebung gelesen (--auth-env) und als Authorization: Bearer, als benutzerdefinierter Header oder als Query-Parameter gesendet
Jede Operation wird zu einem erstklassigen MCP-Tool — Eingabeschemas werden aus parameters + requestBody erzeugt, interne $refs werden aufgelöst
Eingrenzen — --read-only (nur GET), --tag payments, --include /v1/orders, --exclude /admin, plus eine Policy-Ebene für reale APIs: --deny REGEX verbirgt mutierende GETs, --allow REGEX schließt Lese-POST-Endpunkte wieder ein. Deny gewinnt immer.
mcpify doctor — sagt Ihnen, ob Ihre Spezifikation agentenfreundlich ist, bevor Sie sie ausliefern
Operational, nicht nur funktional. mcpify init-Assistent + .mcpify.toml-Konfigurationen mit Abschnitten pro Umgebung, GET-Antwort-Caching (--cache-ttl), sichere Wiederholungsversuche (--retry — nur idempotente Methoden, nur 502/503/504), ausführliches Logging in Logdateien mit maskierten Anmeldedaten, XML→JSON-Konvertierung, strikter Argumentmodus, automatische Origin-Erkennung, Toleranz für Legacy-Batches und ein Health-Check (mcpify status / mcpify_health)
Null Laufzeitabhängigkeiten — der gesamte Baum ist prüfbares Python aus der Standardbibliothek; für YAML-Spezifikationen ist ein optionales pip install 'mcpify[yaml]' erforderlich
Agententaugliche Oberfläche. Tool-Annotationen, die aus HTTP-Semantik abgeleitet sind (Clients genehmigen schreibgeschützte Tools automatisch), strukturierte Ausgabe über MCP outputSchema/structuredContent, Remediation-taugliche Fehler, die den nächsten Aufruf lehren, Dry-Run-Anfragevorschauen und ein --lazy-Modus „Erst suchen, dann aufrufen“, der die Auflistung von api.weather.gov um 95,5 % reduziert hat (38.882 → 1.741 Zeichen)
162 Tests in elf Suiten — darunter ein vollständiger MCP-Protokoll-Lauf über stdio gegen eine echte lokale HTTP-API und das Live-Dokument von api.weather.gov (69 Tools, 16 Parameter mit Enums)
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 | Bedeutung |
| Umgebungsvariable, die die Anmeldedaten enthält |
| wie sie gesendet wird |
| Header-/Query-Name für Nicht-Bearer-Stile (z. B. |
Claude Code:
claude mcp add my-api -- mcpify serve openapi.json --read-onlyClaude Desktop / Cursor / jeder MCP-Client (claude_desktop_config.json):
{
"mcpServers": {
"petstore": {
"command": "mcpify",
"args": ["serve", "~/specs/petstore.json", "--auth-env", "PETSTORE_KEY"]
}
}
}Fragen Sie jetzt Ihren Agenten: „liste die Haustiere auf und erstelle dann eines namens Milo“ — er entdeckt list_pets und create_pet, füllt die Argumente aus und führt echte HTTP-Aufrufe aus.
OpenAPI | mcpify |
| Tool-Name (bereinigt; fällt auf |
| Tool-Beschreibung, die der Agent liest |
| wird von |
| einzelne typisierte Argumente mit Enums |
| ein |
| inline aufgelöst (components → echte Schemas) |
| Standard-Basis-URL (überschreibbar mit |
Der Agent sieht immer nur die Tool-Liste und die JSON-Antworten Ihrer API — mcpify fügt keine Middleware hinzu, cached nichts und sendet Anmeldedaten nirgendwohin außer an Ihre 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-Spezifikationen funktionieren sofort; YAML-Spezifikationen benötigen pip install 'mcpify[yaml]'
Nur lokale $ref-Zeiger werden aufgelöst (bündeln Sie zuerst externe Dokumente — die meisten Tools tun das ohnehin)
Request-Bodies werden als einzelnes body-Objektargument bereitgestellt — vorhersehbar statt ausgeklügelt
Spezifikationsversionen: OpenAPI-3.x- und Swagger-2.x-Wurzeln werden akzeptiert; 3.x ist der bevorzugte Weg
mcpify wird bei jedem Release gegen eine Checkliste mit 10 Kategorien von MCP-Best Practices und veröffentlichten Produktionsfehlermodi geprüft — nicht nur gegen unsere eigenen Beispiele:
Korpus feindseliger Spezifikationen (12/12): zirkuläre $refs, Multipart-Uploads, allOf-Schemas, Server-URL-Variablen, relative Basis-URLs, überdimensionierte Antworten — jedes Szenario stammt aus einem dokumentierten realen Fehler, wurde behoben und durch einen Regressionstest abgesichert. Zu den Quellen gehört die arXiv-Studie zur REST→MCP-Generierung über 18 reale APIs.
Live-Integration: Die echte api.weather.gov-Spezifikation wird in CI geladen — der Fall, der unseren letzten Bug der Absturzklasse gefunden (und behoben) hat.
MCP-Lebenszyklus erzwungen: Tools sind nicht erreichbar, bis der Client den initialize-Handshake abgeschlossen hat.
Kontrollen des Schadensradius: Read-only-Modus, Deny/Allow-Policy-Ebene, Kürzung von Antworten auf 40k Zeichen, --timeout, Anmeldedaten werden nie protokolliert.
Vollständige Checkliste mit Status pro Punkt: docs/AUDIT-CHECKLIST.md
162 bestanden, plus ein Live-Integrationstest, der das echte api.weather.gov-Dokument lädt (bei Offline-Betrieb automatisch übersprungen). Jede Suite läuft auf Python 3.10–3.12 unter Linux und Windows; ruff, striktes mypy und CodeQL prüfen jeden Push.
Suite | Tests | Was sie absichert |
Spezifikations-Parsing & -Auflösung | 13 | OpenAPI-3.x- und YAML-Laden, |
Tool-Übersetzung | 19 | operationId-Benennung mit Kollisions-Suffixen, Eingabeschemas, Enums, Body-Handling, Ableitung von Annotationen & Ausgabeschemas |
Agentenoberfläche | 31 | Aus HTTP abgeleitete Annotationen, Vertrag für strukturierte Ausgaben, Remediation-Fehler, |
CLI | 15 |
|
Feindseliger Korpus | 11 | zirkuläre |
Lebenszyklus & Hygiene | 8 | initialize-Handshake ( |
Protokoll Ende-zu-Ende | 9 | echtes JSON-RPC über stdio gegen eine echte lokale HTTP-API, Assertions auf Drahtebene |
Policy-Ebene | 7 |
|
| 4 | Parameterschemas, die gegen die vollständige Spezifikation aufgelöst werden — die weather.gov-Fehlerklasse (ein Test trifft das Live-Dokument) |
Betrieb & Konfiguration | 41 | Konfigurationsdateien + Umgebungsvariablen-Priorität, Init-Assistent, Cache-TTL & -Grenzen, Retry-Sicherheit, XML-Konvertierung, Discovery, Batching, Status/Health |
Protokollversions-Kompatibilität | 5 | 2026-07-28 zustandslose |
Grundsatz bei Fehlern: Jeder in freier Wildbahn gefundene Bug wird vor der Auslieferung des Fixes zu einem fest verankerten Regressionstest — die Suite wächst nur.
Lokal ausführen:
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 — ein eigenständiges, teilbares Server-Skript erzeugen
Rate-Limiting pro Operation
OAuth2-Client-Credentials-Flow
MIT — siehe die Datei LICENSE für Details.
[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.
