MCP-Server aus OpenAPI generieren

Mach aus dem OpenAPI-Dokument deiner API einen funktionierenden MCP-Server, ein Tool pro Endpunkt.

Statt einen MCP-Server von Hand zu schreiben, verweist du Tuix AI Agents auf das öffentliche OpenAPI-Dokument (Swagger) deiner API. Die Plattform liest es und generiert einen echten, bereitgestellten MCP-Server, mit einem Tool pro markiertem Endpunkt, der sich automatisch mit dem Agenten deiner Anwendung verbindet, sobald er bereit ist.

Was du brauchst

Ein öffentlich erreichbares OpenAPI-Dokument im JSON-Format.
Die Endpunkte, die der Agent nutzen soll, markiert mit x-mcp: true.

Die freizugebenden Endpunkte markieren

Füge x-mcp: true zu jeder Operation hinzu, die zu einem Tool werden soll:

{
    "paths": {
        "/employees": {
            "get": {
                "operationId": "getEmployees",
                "description": "List employees",
                "x-mcp": true,
                "parameters": [
                    {
                        "name": "page",
                        "in": "query",
                        "schema": { "type": "integer" }
                    }
                ]
            }
        }
    },
    "info": {
        "title": "My API Service",
        "version": "1.0.0"
    }
}

Für eine so markierte Operation wird der Generator:

Ein Tool erzeugen, benannt nach ihrer operationId, umgewandelt in snake_case, z. B. getEmployees → get_employees.
Jeden Query- und Path-Parameter sowie jedes Feld des Request-Bodys als Tool-Eingabe einschließen.

Header- und Cookie-Parameter werden derzeit nicht zu Tool-Eingaben umgewandelt. Wenn ein Endpunkt einen davon benötigt, mache ihn stattdessen über einen Query-Parameter oder den Request-Body verfügbar, oder behandle ihn über die security-Zuordnung unten.

Das Tool mit deiner eigenen Authentifizierung schützen

Füge einer Operation eine security-Anforderung hinzu, damit der generierte Server dafür einen Authorization-Header verlangt und weiterleitet:

{
    "paths": {
        "/employees": {
            "get": {
                "operationId": "getEmployees",
                "description": "List employees",
                "x-mcp": true,
                "security": [
                    {
                        "jwt": ["get:employees"]
                    }
                ]
            }
        }
    },
    "info": {
        "title": "My API Service",
        "version": "1.0.0"
    }
}

Ist security vorhanden, wird ein Aufruf dieses Tools ohne Authorization-Header abgelehnt, bevor er überhaupt deine API erreicht. Siehe Autorisierung für die genaue Durchsetzung und Weiterleitung.

Rollenverwaltung

Füge einer Operation x-role hinzu, um ihr Tool mit einer oder mehreren Rollen zu markieren:

{
    "paths": {
        "/employees": {
            "get": {
                "operationId": "getEmployees",
                "description": "List employees",
                "x-role": ["service-admin", "service-assistant"]
            }
        }
    },
    "info": {
        "title": "My API Service",
        "version": "1.0.0"
    }
}

Die Rollen landen im _meta-Feld des generierten Tools, dem Standardort, an dem ein MCP-Tool Metadaten trägt, sodass jeder Client, der Tools auflistet, lesen kann, für welche Rollen ein Tool gedacht ist:

{
    "name": "get_employees",
    "description": "List employees",
    "inputSchema": {
        "type": "object",
        "properties": {
            "page": {
                "type": "integer",
                "description": "Page number"
            }
        },
        "required": []
    },
    "annotations": {
        "title": "List employees",
        "readOnlyHint": true,
        "destructiveHint": false,
        "idempotentHint": true,
        "openWorldHint": true
    },
    "_meta": {
        "x-role": ["service-admin", "service-assistant"]
    }
}

x-role ist Metadaten, keine Zugriffskontrolle: Der MCP-Server selbst prüft sie nicht und ruft deine API weiterhin genau so auf, wie konfiguriert, für jeden, der das Tool aufruft. Dein Tuix-Agent ist es, der diese Metadaten liest, um einem Aufrufer nur die zu seiner Rolle passenden Tools anzubieten, siehe Rollenumfang.

Unterstützung für Formulardaten

Eine Operation ist nicht auf einen JSON-Body beschränkt, multipart/form-data wird für Endpunkte, die es brauchen, ebenfalls unterstützt, typischerweise für einen Datei-Upload:

{
    "paths": {
        "/employees": {
            "post": {
                "operationId": "createEmployees",
                "x-mcp": true,
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "type": "object",
                                "properties": {
                                    "file": {
                                        "type": "string",
                                        "format": "binary",
                                        "description": "Signed contract"
                                    },
                                    "name": {
                                        "type": "string",
                                        "description": "Employee name"
                                    }
                                },
                                "required": ["file", "name"]
                            }
                        }
                    }
                }
            }
        }
    },
    "info": {
        "title": "My API Service",
        "version": "1.0.0"
    }
}

Jede Eigenschaft wird zu einer Tool-Eingabe, benannt nach ihrem Eigenschaftsschlüssel, dieselbe Regel wie bei einem JSON-Body. Eine mit "format": "binary" markierte Eigenschaft wird zu einer Datei-Eingabe: Das Tool dokumentiert sie als Erwartung des Dateiinhalts base64-kodiert, da ein JSON-RPC-Tool-Aufruf keine Möglichkeit hat, rohe Binärdaten zu tragen.

Ein Tool-Aufruf ist durchgehend reines JSON-RPC, unabhängig davon, was der zugrunde liegende Endpunkt erwartet. Bei einer multipart/form-data-Operation dekodiert der generierte MCP-Server den base64-Wert zurück in Bytes und baut auf dem Weg zu deiner API eine echte Multipart-Anfrage: Nicht-Datei-Felder werden zu Formularfeldern, Datei-Felder zu Datei-Teilen, mit automatisch gesetzter Boundary und Content-Type.

Den Server generieren

Klicke im Tab MCP Servers der Anwendung auf Add MCP Server und füge die URL deines OpenAPI-Dokuments ein.

Warte, bis sich der Status von Generating zu Deployed ändert.

Das Ergebnis ist ein funktionsfähiger Streamable-HTTP-MCP-Server. Er verbindet sich automatisch mit dem Agenten dieser Anwendung und kann auch von externen Agenten erreicht werden, siehe Mit einem Agenten verbinden.

Dialog zum Hinzufügen eines MCP-Servers und Status-Badges im Tuix-Dashboard

Schlägt die Generierung fehl, zeigt der Server den Status Failed und wird automatisch zerstört.

Einschränkungen

Jedes aus einem Dokument generierte Tool ruft dieselbe Basis-URL auf: den Ursprung des OpenAPI-Dokuments selbst. Alle Endpunkte in einem Dokument gelten als zum selben Dienst gehörend.
Das erneute Generieren aus einer bereits verwendeten OpenAPI-Dokument-URL erzeugt keinen zweiten Server: Du erhältst denselben, bereits bereitgestellten Server zurück.

Aus OpenAPI generieren