Skip to main content Skip to page footer

Claude Desktop

Claude Desktop läuft lokal auf macOS, Windows oder Linux. Wie dein MCP-Server erreichbar sein muss, hängt vom Weg ab. Über die Brücke mcp-remote oder den lokalen stdio-Transport baut dein Rechner die Verbindung auf, nicht Anthropics Infrastruktur. Der MCP-Server muss dann nicht öffentlich erreichbar sein. Es funktionieren localhost, *.ddev.site, interne DNS-Namen und selbstsignierte Zertifikate, solange dein Betriebssystem der ausstellenden CA vertraut. Für die Brücke mcp-remote braucht Node.js die CA zusätzlich, siehe Abschnitt zu selbstsignierten Zertifikaten. Ein eigener Connector (siehe unten) läuft dagegen wie bei Claude.ai über Anthropics Infrastruktur und braucht einen öffentlich per HTTPS erreichbaren Server.

Zur Authentifizierung empfiehlt sich für Claude Desktop ein statisches Bearer-Token, das im Backend der AI Suite erzeugt wird. Das ist der einfachste Weg und kommt ohne OAuth-Einrichtung aus. Alternativ ist der OAuth-Flow möglich (identisch zu Claude.ai). Läuft TYPO3 auf demselben Rechner, gibt es zusätzlich einen lokalen stdio-Modus, siehe Lokaler stdio-Transport.

Voraussetzungen

  • enableMcp ist aktiviert (siehe Konfiguration).
  • 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. In der Produktion bleibt der Wert 0. Die Brücke mcp-remote braucht für HTTP außerhalb von localhost zusätzlich das Argument --allow-http, siehe Dokumentation von mcp-remote.
  • Die Backend-Gruppe besitzt enable_mcp_access und die benötigten Feature-Rechte (siehe Berechtigungen & Scopes).
  • Der TYPO3-Host ist von deinem Rechner aus erreichbar. Ein Aufruf von [typo3-url]/aisuite-mcp/health muss 200 liefern. Bei selbstsigniertem Zertifikat (z. B. DDEV) die CA im System hinterlegen (mkcert -install) und für die Brücke NODE_EXTRA_CA_CERTS setzen (siehe Abschnitt zu selbstsignierten Zertifikaten).
  • Claude Desktop ist installiert.

Verbindung einrichten

1. Token erstellen. Öffne im Backend-Modul „AI Suite“ den Reiter MCP und klicke auf Token erstellen. Es wird ein an deinen Backend-Benutzer gebundenes Token mit allen Scopes erzeugt, zu denen du berechtigt bist. Kopiere den angebotenen claude_desktop_config.json-Ausschnitt. Die Gültigkeit steuert mcpTokenLifetimeDays (Standard 30 Tage).

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "[typo3-url]/aisuite-mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer [token]"
      }
    }
  }
}

Der Header-Wert steht in einer Umgebungsvariable, weil Claude Desktop unter Windows Argumente mit Leerzeichen zerlegt. Das Snippet aus dem MCP-Dashboard schreibt den Header noch direkt in args. Übernimm das Token daraus, verwende aber die Schreibweise oben. Alternativ liest mcp-remote die Header mit --header-file aus einer Datei, siehe Dokumentation von mcp-remote.

Warum ein Befehl und keine URL? Die claude_desktop_config.json nimmt nur lokal gestartete stdio-Server an, also command, args und env. Einen Eintrag mit url und headers lädt Claude Desktop nicht und meldet stattdessen einen Fehler in der Konfiguration. Die Brücke mcp-remote läuft deshalb lokal und leitet mit angehängtem Bearer-Token an den HTTP-Endpoint weiter. Sie braucht Node.js in einer aktuellen LTS-Version auf dem Rechner, auf dem Claude Desktop läuft. Wer ohne Brücke arbeiten will, hat zwei Alternativen: den eigenen Connector per OAuth (siehe unten) oder den lokalen Transport, siehe Lokaler stdio-Transport.

2. Snippet einfügen. Trage den Ausschnitt in die Konfigurationsdatei claude_desktop_config.json von Claude Desktop ein. Wo die Datei liegt und wie du sie aus Claude Desktop heraus öffnest, beschreibt die Anleitung zu lokalen MCP-Servern in Claude Desktop. Sichere die Datei vorher. Vorhandene Einträge unter mcpServers nicht überschreiben, sondern ergänzen. Danach Claude Desktop vollständig beenden und neu starten (Fenster schließen genügt nicht).

3. Verbindung prüfen. Öffne eine neue Unterhaltung und prüfe in der Connector-Auswahl am Eingabefeld, ob der Eintrag typo3-ai-suite mit den AI-Suite-Tools erscheint (readServerInfo, listTables, readPageTree usw.). Die Tools müssen pro Unterhaltung eingeschaltet sein.

Selbstsignierte Zertifikate (DDEV, mkcert)

Das ist der häufigste Stolperstein bei lokalen Umgebungen mit DDEV oder mkcert. mkcert -install legt die CA in den Zertifikatsspeicher des Betriebssystems, was für Browser und curl reicht. Node.js ignoriert diesen Speicher und bringt einen eigenen CA-Vorrat mit. Die Brücke scheitert deshalb mit UNABLE_TO_VERIFY_LEAF_SIGNATURE, obwohl dieselbe URL im Browser mit 200 antwortet.

Die Lösung ist ein zusätzlicher Eintrag im env-Block desselben Servereintrags, der Node.js auf die mkcert-Wurzel zeigt. Das Verzeichnis nennt dir mkcert -CAROOT.

{
  "mcpServers": {
    "typo3-ai-suite": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "[typo3-url]/aisuite-mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": {
        "AUTH_HEADER": "Bearer [token]",
        "NODE_EXTRA_CA_CERTS": "[mkcert -CAROOT]/rootCA.pem"
      }
    }
  }
}

Prüfe das am besten erst außerhalb von Claude Desktop:

NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" \
  node -e "require('https').get('[typo3-url]/aisuite-mcp/health', r => console.log(r.statusCode))"

Genau daran liegt es, wenn ein *.ddev.site-Host für Claude Desktop unerreichbar wirkt. Ein Tunnel über cloudflared oder ngrok ist nicht nötig, die Brücke löst lokale Hostnamen problemlos auf.

Fehlerbehebung

  • Server fehlt in der Tool-Liste: Die claude_desktop_config.json hat einen JSON-Syntaxfehler oder liegt im falschen Pfad. Datei prüfen (z. B. python -m json.tool) und Pfad mit der oben verlinkten Anleitung abgleichen.
  • Claude Desktop meldet einen Fehler in der MCP-Konfiguration: Der Servereintrag enthält url, transport oder headers statt command und args. Ältere Versionen des MCP-Dashboards haben an dieser Stelle die HTTP-Form ausgegeben. Token neu erzeugen und das Token in die Schreibweise mit env (siehe oben) übernehmen oder auf den eigenen Connector beziehungsweise den lokalen Transport wechseln, siehe Lokaler stdio-Transport.
  • npx: command not found oder der Eintrag bleibt in der Tool-Liste grau: Die Brücke mcp-remote braucht Node.js auf dem Rechner mit Claude Desktop, und GUI-Programme starten mit einem sehr kurzen PATH. Node.js in einer aktuellen LTS-Version systemweit installieren, sodass es im PATH des Systems liegt, oder "npx" durch den absoluten Pfad ersetzen, etwa /usr/local/bin/npx. Vorher die Brücke von Hand testen.
  • 401 oder „Authentication required“: Token ungültig, abgelaufen oder widerrufen. Token neu erzeugen.
  • 404: Die URL enthält ein Site-Präfix. Verwende die Wurzel-URL [typo3-url]/aisuite-mcp.
  • SSL-Zertifikatsfehler, etwa UNABLE_TO_VERIFY_LEAF_SIGNATURE: Selbstsigniertes Zertifikat. Ein mkcert -install allein genügt für die Brücke nicht, weil Node.js einen eigenen CA-Vorrat mitbringt und den Zertifikatsspeicher des Systems ignoriert. Siehe den Abschnitt zu selbstsignierten Zertifikaten.
  • Modell meldet „kein MCP-Zugriff“: Die AI-Suite-Tools sind in der Unterhaltung nicht eingeschaltet. In der Connector-Auswahl am Eingabefeld einschalten.
  • Ursache weiter eingrenzen: Claude Desktop schreibt für jeden MCP-Server ein eigenes Log. Wo es liegt, beschreibt die Anleitung zum Debuggen von MCP-Servern.

Weitere clientunabhängige Fälle (Authorization-Header, fehlende Tools, deaktivierter Endpoint) sind unter Clients verbinden gesammelt. Die ausführliche Anleitung steht im Connector-Guide im Repository.

Alternative: eigener Connector (OAuth statt statischem Token)

Claude Desktop kann einen entfernten MCP-Server auch ganz ohne Konfigurationsdatei ansprechen, als eigenen Connector. Lege in Claude einen eigenen Connector an und trage als URL [typo3-url]/aisuite-mcp ein. Wähle unter Authentication „Sign in now“ und unter OAuth client „Register automatically“. Die voreingestellte Option „Use Claude's published identity“ setzt Client ID Metadata Documents voraus, die AI Suite MCP nicht anbietet. Wo das in deinem Tarif liegt, wer in einer Organisation den Connector anlegen darf und welche Felder der Dialog zeigt, beschreibt die Anleitung von Anthropic zu eigenen Connectors. Claude Desktop führt dann den OAuth-2.1-Ablauf gegen den MCP-Server durch, inklusive dynamischer Client-Registrierung (Dynamic Client Registration), und verwaltet die Tokens selbst.

Zwei Unterschiede zum Weg über das Token:

  • OAuth statt Header. Eigene Request-Header, über die sich das statische Bearer-Token mitsenden ließe, bietet Claude nur eingeschränkt an, und ein dort hinterlegtes Token gilt für alle Mitglieder der Organisation (siehe die oben verlinkte Anleitung von Anthropic). Nutze deshalb OAuth. Dafür müssen mcpAllowedRedirectUris und mcpAllowedOrigins gefüllt sein. Die Werte sind dieselben wie bei Claude.ai.
  • Kein Node.js nötig, weil lokal nichts gestartet wird.

Ein eigener Connector läuft wie bei Claude.ai über Anthropics Infrastruktur und braucht deshalb einen öffentlich per HTTPS erreichbaren Server. Für lokale Hosts nutzt du den lokalen Transport (siehe Lokaler stdio-Transport) oder die Brücke mcp-remote.