MCP Inspector

Der MCP Inspector ist das offizielle Debugging-Werkzeug für MCP-Server, eine kleine browserbasierte Oberfläche, die bei Bedarf über npx gestartet wird. Er ist der schnellste Weg, den MCP-Server von Hand zu testen, ohne ein Sprachmodell dazwischen. Du rufst Tools mit selbst gebauten Argumenten auf und siehst den rohen JSON-RPC-Verkehr in beide Richtungen. Für Skripte gibt es zusätzlich einen CLI-Modus ohne Oberfläche, siehe README des MCP Inspectors.

Der Inspector läuft lokal, die Verbindung kommt von deinem Rechner. Der MCP-Server muss daher nicht öffentlich erreichbar sein. Es funktionieren localhost, *.ddev.site, interne DNS-Namen und selbstsignierte Zertifikate, solange dein Betriebssystem der CA vertraut.

Voraussetzungen

enableMcp ist aktiviert (siehe Konfiguration).
mcpAllowedRedirectUris und mcpAllowedOrigins sind nicht nötig. localhost, 127.0.0.1 und [::1] werden unabhängig von diesen Einstellungen immer akzeptiert.
mcpAllowHttp setzt du nur dann auf 1, wenn deine TYPO3-URL reines HTTP ist und der Host weder localhost, 127.0.0.1, [::1] noch *.ddev.site ist. Diese Hosts sind ohnehin ausgenommen. Produktiv bleibt der Wert 0.
Die Backend-Gruppe besitzt enable_mcp_access und die benötigten Feature-Rechte (siehe Berechtigungen & Scopes).
Node.js ab Version 22.19 ist installiert (siehe README des MCP Inspectors). Den Inspector selbst musst du nicht installieren, npx holt ihn bei Bedarf.
curl -sS [typo3-url]/aisuite-mcp/health liefert von diesem Rechner aus 200.

Inspector starten

1. Inspector starten. Führe den folgenden Befehl in einem Terminal auf deinem Rechner aus. Die Angabe --transport http ist nötig, weil der Pfad /aisuite-mcp nicht auf /mcp endet:

MCP Inspector starten

npx @modelcontextprotocol/inspector --transport http --server-url [typo3-url]/aisuite-mcp

Oberfläche öffnen und verbinden

Die Ausgabe nennt die URL der Oberfläche (127.0.0.1) samt Zugangstoken und öffnet sie im Standardbrowser. Öffne die Oberfläche über genau diese URL, weil sie das Zugangstoken enthält.

2. Verbindung konfigurieren. Der Startbefehl legt den Server mit dem Transport Streamable HTTP und der URL [typo3-url]/aisuite-mcp bereits an. Wähle in den Server-Einstellungen OAuth als Authentifizierung oder trage für ein statisches Token den Header Authorization: Bearer [token] ein. Wie die Felder heißen und wo sie liegen, beschreibt das README des MCP Inspectors.

3. OAuth abschließen. Beim Verbinden registriert sich der Inspector unter [typo3-url]/aisuite-mcp/oauth/register und öffnet die Autorisierungsseite. Dort meldest du dich mit deinen TYPO3-Backend-Zugangsdaten an, auch wenn du im Backend schon angemeldet bist, und stimmst den Scopes zu. Der Browser leitet auf 127.0.0.1/oauth/callback zurück. Diese Adresse ist durch die localhost-Ausnahme abgedeckt, ein Eintrag in mcpAllowedRedirectUris ist nicht nötig. Der Inspector tauscht den Code gegen ein Access-Token und speichert es selbst. Danach stehen Tools, Ressourcen und Prompts zum Testen bereit.

Tools manuell aufrufen

Der eigentliche Nutzen des Inspectors liegt darin, Tools direkt mit selbst gebauten JSON-Argumenten aufzurufen, ohne Sprachmodell. Die Oberfläche zeigt zu jedem Aufruf die rohe JSON-RPC-Anfrage und die Antwort. Damit lassen sich Schema-Abweichungen und Rechteprobleme sehr schnell einkreisen.

Als Einstieg bewährt sich diese Reihenfolge:

Tool	Argumente	Erwartetes Ergebnis
`readServerInfo`	keine	Serverstatus mit MCP-Version, aktivem Workspace und Sites (für Admins zusätzlich die Versionen von AI Suite, PHP und TYPO3 sowie Konfiguration und Diagnose)
`listTables`	keine	Liste der für den Backend-Benutzer zugänglichen Tabellen
`readPageTree`	`{ "rootPageId": 0, "depth": 2 }`	Verschachteltes JSON des Seitenbaums

Kommt bereits readServerInfo nicht durch, liegt das Problem an Verbindung oder Berechtigung und nicht am jeweiligen Tool.

Fehlerbehebung

Beim Verbinden passiert nichts, und im TYPO3-Log steht nichts. Der Server ist von deinem Rechner aus nicht erreichbar, oder DNS beziehungsweise TLS scheitert lokal. Mit curl [typo3-url]/aisuite-mcp/health vom selben Rechner prüfen, bei selbstsignierten Zertifikaten mkcert -install ausführen.

Der Browser meldet beim Redirect ein Zertifikatsproblem. Die CA des TYPO3-Hosts ist dem Browser nicht bekannt. CA auf Betriebssystemebene vertrauen und den Browser neu starten. Ein curl -k hilft hier nicht weiter, Browser sind bei OAuth-Weiterleitungen strenger.

Weitere Fehlermeldungen zeigen das Terminal, in dem der Inspector läuft, und die Browser-Konsole. Die OAuth-Zugangsdaten und Tokens speichert der Inspector selbst. Um die Anmeldung zurückzusetzen, setzt du den OAuth-Zustand in den Server-Einstellungen des Inspectors zurück und verbindest dich neu. Weitere clientunabhängige Fälle sind unter Clients verbinden gesammelt.