`mcp-remote`

Verbinden Sie einen MCP-Client, der nur lokale (stdio-)Server unterstützt, mit einem Remote-MCP-Server – inklusive Authentifizierungsunterstützung:

Hinweis: Dies ist ein funktionierender Proof-of-Concept, sollte aber als experimentell betrachtet werden.

Warum ist das notwendig?

Bisher wird die Mehrheit der MCP-Server in freier Wildbahn lokal installiert und nutzt den Stdio-Transport. Das hat einige Vorteile: Sowohl der Client als auch der Server können einander implizit vertrauen, da der Nutzer beiden die Ausführung erlaubt hat. Geheimnisse wie API-Schlüssel können über Umgebungsvariablen hinzugefügt werden und verlassen Ihren Rechner nie. Und die Nutzung von npx und uvx hat es Anwendern ebenfalls ermöglicht, explizite Installationsschritte zu vermeiden.

Aber es gibt einen Grund, warum die meiste Software, die ins Web verlagert werden konnte, tatsächlich ins Web verlagert wurde: Es ist so viel einfacher, Fehler zu finden und zu beheben und an neuen Funktionen zu iterieren, wenn Sie Updates mit einem einzigen Deployment an alle Ihre Nutzer ausliefern können.

Mit der neuesten MCP-Authorization-Spezifikation haben wir nun eine sichere Möglichkeit, unsere MCP-Server mit der Welt zu teilen, ohne Code auf den Laptops der Nutzer auszuführen. Oder zumindest hätten Sie das, wenn alle gängigen MCP-Clients dies bereits unterstützen würden. Die meisten unterstützen nur Stdio, und diejenigen, die HTTP+SSE doch unterstützen, beherrschen die erforderlichen OAuth-Abläufe noch nicht.

Hier kommt mcp-remote ins Spiel. Sobald Ihr gewählter MCP-Client Remote-Server mit Autorisierung unterstützt, können Sie es entfernen. Bis dahin fügen Sie diesen Einzeiler ein und machen Sie sich für die MCP-Clients bereit, die Sie möchten!

Verwendung

Alle der gängigsten MCP-Clients (Claude Desktop, Cursor & Windsurf) verwenden das folgende Konfigurationsformat:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]
    }
  }
}

Benutzerdefinierte Header

Um die Authentifizierung zu umgehen oder bei allen Anfragen an Ihren Remote-Server benutzerdefinierte Header zu senden, übergeben Sie --header-CLI-Argumente:

{
  "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--header",
        "Authorization: Bearer ${AUTH_TOKEN}"
      ],
      "env": {
        "AUTH_TOKEN": "..."
      }
    },
  }
}

Hinweis: Cursor und Claude Desktop (Windows) haben einen Bug, bei dem Leerzeichen innerhalb von args nicht maskiert werden, wenn npx aufgerufen wird, wodurch diese Werte verstümmelt werden. Sie können dies wie folgt umgehen:

{
  // rest of config...
  "args": [
    "mcp-remote",
    "https://remote.mcp.server/sse",
    "--header",
    "Authorization:${AUTH_HEADER}" // note no spaces around ':'
  ],
  "env": {
    "AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
  }
},

Flags

Wenn npx Fehler erzeugt, sollten Sie erwägen, -y als erstes Argument hinzuzufügen, um die Installation des Pakets mcp-remote automatisch zu bestätigen.

      "command": "npx",
      "args": [
        "-y"
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ]

Um npx zu zwingen, immer nach einer aktualisierten Version von mcp-remote zu suchen, fügen Sie das @latest-Flag hinzu:

      "args": [
        "mcp-remote@latest",
        "https://remote.mcp.server/sse"
      ]

Um den Port zu ändern, auf dem mcp-remote auf eine OAuth-Weiterleitung lauscht (standardmäßig 3334), fügen Sie nach der Server-URL ein zusätzliches Argument hinzu. Beachten Sie, dass unabhängig vom angegebenen Port ein freier Port zufällig gewählt wird, falls dieser nicht verfügbar ist.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "9696"
      ]

Um den Host zu ändern, den mcp-remote als OAuth-Callback-URL registriert (standardmäßig localhost), fügen Sie das --host-Flag hinzu.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--host",
        "127.0.0.1"
      ]

Um HTTP-Verbindungen in vertrauenswürdigen privaten Netzwerken zu erlauben, fügen Sie das --allow-http-Flag hinzu. Hinweis: Dies sollte nur in sicheren privaten Netzwerken verwendet werden, in denen Datenverkehr nicht abgefangen werden kann.

      "args": [
        "mcp-remote",
        "http://internal-service.vpc/sse",
        "--allow-http"
      ]

Um detaillierte Debug-Logs zu aktivieren, fügen Sie das --debug-Flag hinzu. Dies schreibt ausführliche Logs in ~/.mcp-auth/{server_hash}_debug.log mit Zeitstempeln und detaillierten Informationen über den Authentifizierungsprozess, Verbindungen und die Token-Aktualisierung.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--debug"
      ]

Um einen ausgehenden HTTP(S)-Proxy für mcp-remote zu aktivieren, fügen Sie das --enable-proxy-Flag hinzu. Wenn aktiviert, verwendet mcp-remote die Proxy-Einstellungen aus gängigen Umgebungsvariablen (z. B. HTTP_PROXY, HTTPS_PROXY und NO_PROXY).

    "args": [
      "mcp-remote",
      "https://remote.mcp.server/sse",
      "--enable-proxy"
    ],
    "env": {
      "HTTPS_PROXY": "http://127.0.0.1:3128",
      "NO_PROXY": "localhost,127.0.0.1"
    }

Um bestimmte Tools des Remote-Servers zu ignorieren, fügen Sie das --ignore-tool-Flag hinzu. Dadurch werden Tools, die den angegebenen Mustern entsprechen, sowohl aus tools/list-Antworten herausgefiltert als auch tools/call-Anfragen blockiert. Wildcard-Muster mit * werden unterstützt.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--ignore-tool",
        "delete*",
        "--ignore-tool",
        "remove*"
      ]

Sie können mehrere --ignore-tool-Flags angeben, um verschiedene Muster zu ignorieren. Beispiele:

delete* - ignoriert alle Tools, die mit „delete“ beginnen (z. B. deleteTask, deleteUser)
*account - ignoriert alle Tools, die mit „account“ enden (z. B. getAccount, updateAccount)
exactTool - ignoriert nur das Tool, das exakt „exactTool“ heißt

Um den Timeout für den OAuth-Callback zu ändern (standardmäßig 30 Sekunden), fügen Sie das --auth-timeout-Flag mit einem Wert in Sekunden hinzu. Dies ist nützlich, wenn der Authentifizierungsprozess auf der Serverseite lange dauert.

      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse",
        "--auth-timeout",
        "60"
      ]

Transport-Strategien

MCP Remote unterstützt verschiedene Transportstrategien, wenn es sich mit einem MCP-Server verbindet. Damit können Sie steuern, ob Server-Sent Events (SSE) oder der HTTP-Transport verwendet wird und in welcher Reihenfolge die Strategien ausprobiert werden.

Geben Sie die Transportstrategie mit dem --transport-Flag an:

npx mcp-remote https://example.remote/server --transport sse-only

Verfügbare Strategien:

http-first (Standard): Versucht zuerst den HTTP-Transport und fällt auf SSE zurück, wenn HTTP mit einem 404-Fehler fehlschlägt
sse-first: Versucht zuerst den SSE-Transport und fällt auf HTTP zurück, wenn SSE mit einem 405-Fehler fehlschlägt
http-only: Verwendet nur den HTTP-Transport und schlägt fehl, wenn der Server ihn nicht unterstützt
sse-only: Verwendet nur den SSE-Transport und schlägt fehl, wenn der Server ihn nicht unterstützt

Statische OAuth-Client-Metadaten

MCP Remote unterstützt die Bereitstellung statischer OAuth-Client-Metadaten anstelle der mcp-remote-Standardwerte. Dies ist nützlich, wenn Sie sich mit OAuth-Servern verbinden, die bestimmte Client-/Software-IDs oder Scopes erwarten.

Geben Sie die Client-Metadaten mit dem --static-oauth-client-metadata-Flag als JSON-String oder als Dateipfad mit @-Präfix an:

npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'

Statische OAuth-Client-Informationen

Gemäß der Spezifikation werden Server ermutigt, aber nicht verpflichtet, die dynamische OAuth-Client-Registrierung zu unterstützen.

Für diese Server unterstützt MCP Remote stattdessen die Bereitstellung statischer OAuth-Client-Informationen. Dies ist nützlich, wenn Sie sich mit OAuth-Servern verbinden, die vorab registrierte Clients erfordern.

Geben Sie die Client-Metadaten mit dem --static-oauth-client-info-Flag als JSON-String oder als Dateipfad mit @-Präfix an:

export MCP_REMOTE_CLIENT_ID=xxx
export MCP_REMOTE_CLIENT_SECRET=yyy
npx mcp-remote https://example.remote/server --static-oauth-client-info "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'

Claude Desktop

Offizielle Dokumentation

Um einen MCP-Server zu Claude Desktop hinzuzufügen, müssen Sie die Konfigurationsdatei an folgendem Speicherort bearbeiten:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Falls sie noch nicht existiert, müssen Sie sie möglicherweise unter Einstellungen > Entwickler aktivieren.

Starten Sie Claude Desktop neu, um die Änderungen in der Konfigurationsdatei zu übernehmen. Nach dem Neustart sollten Sie ein Hammersymbol in der unteren rechten Ecke des Eingabefelds sehen.

Cursor

Offizielle Dokumentation. Die Konfigurationsdatei befindet sich unter ~/.cursor/mcp.json.

Ab Version 0.48.0 unterstützt Cursor nicht authentifizierte SSE-Server direkt. Wenn Ihr MCP-Server das offizielle MCP-OAuth-Autorisierungsprotokoll verwendet, müssen Sie dennoch einen „command“-Server hinzufügen und mcp-remote aufrufen.

Windsurf

Offizielle Dokumentation. Die Konfigurationsdatei befindet sich unter ~/.codeium/windsurf/mcp_config.json.

Remote-MCP-Server erstellen

Anleitungen zum Erstellen und Bereitstellen von Remote-MCP-Servern, einschließlich der Rolle als gültiger OAuth-Client, finden Sie in den folgenden Ressourcen:

https://developers.cloudflare.com/agents/guides/remote-mcp-server/

Insbesondere siehe:

https://github.com/cloudflare/workers-oauth-provider zum Definieren eines MCP-konformen OAuth-Servers in Cloudflare Workers
https://github.com/cloudflare/agents/tree/main/examples/mcp zum Definieren eines McpAgent mit dem agents-Framework.

Weitere Informationen zum Testen dieser Server finden Sie außerdem unter:

https://developers.cloudflare.com/agents/guides/test-remote-mcp-server/

Kennen Sie weitere Ressourcen, die Sie teilen möchten? Fügen Sie sie bitte dieser Readme hinzu und senden Sie einen PR!

Fehlerbehebung

Leeren Sie Ihr `~/.mcp-auth`-Verzeichnis

mcp-remote speichert alle Anmeldeinformationen in ~/.mcp-auth (oder wohin auch immer Ihre MCP_REMOTE_CONFIG_DIR verweist). Wenn Sie anhaltende Probleme haben, versuchen Sie Folgendes auszuführen:

rm -rf ~/.mcp-auth

Starten Sie anschließend Ihren MCP-Client neu.

Überprüfen Sie Ihre Node-Version

Stellen Sie sicher, dass die von Ihnen installierte Node-Version 18 oder höher ist. Claude Desktop verwendet Ihre Systemversion von Node, selbst wenn Sie an anderer Stelle eine neuere Version installiert haben.

Claude neu starten

Beim Ändern von claude_desktop_config.json kann es hilfreich sein, Claude vollständig neu zu starten.

VPN-Zertifikate

Wenn Sie sich hinter einem VPN befinden, können Probleme auftreten. Sie können versuchen, die Umgebungsvariable NODE_EXTRA_CA_CERTS so zu setzen, dass sie auf die CA-Zertifikatsdatei verweist. Bei Verwendung von claude_desktop_config.json könnte das wie folgt aussehen:

{
 "mcpServers": {
    "remote-example": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote.mcp.server/sse"
      ],
      "env": {
        "NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
      }
    }
  }
}

Überprüfen Sie die Logs

Claude-Desktop-Logs in Echtzeit verfolgen
MacOS / Linux:
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
Für Bash unter WSL:
tail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"
PowerShell:
Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20

Debugging

Debug-Logs

Zur Fehlerbehebung bei komplexen Problemen, insbesondere bei der Token-Aktualisierung oder bei Authentifizierungsproblemen, verwenden Sie das --debug-Flag:

"args": [
  "mcp-remote",
  "https://remote.mcp.server/sse",
  "--debug"
]

Dadurch werden detaillierte Logs in ~/.mcp-auth/{server_hash}_debug.log mit Zeitstempeln und vollständigen Informationen zu jedem Schritt des Verbindungs- und Authentifizierungsprozesses erstellt. Wenn Sie Probleme mit der Token-Aktualisierung, Laptop-Schlaf-/Aufwach-Problemen oder Authentifizierungsproblemen feststellen, legen Sie diese Logs vor, wenn Sie Unterstützung suchen.

Authentifizierungsfehler

Wenn Sie den folgenden Fehler erhalten, der von der /callback-URL zurückgegeben wird:

Authentication Error
Token exchange failed: HTTP 400

Sie können rm -rf ~/.mcp-auth ausführen, um lokal gespeicherte Zustände und Token zu löschen.

„Client“-Modus

Führen Sie Folgendes auf der Befehlszeile aus (nicht von einem MCP-Server):

npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server/sse

Dadurch wird der gesamte Autorisierungsablauf durchlaufen und versucht, die Tools und Ressourcen unter der Remote-URL aufzulisten. Versuchen Sie dies, nachdem Sie rm -rf ~/.mcp-auth ausgeführt haben, um zu sehen, ob veraltete Anmeldeinformationen Ihr Problem sind. Andernfalls ist das Problem hoffentlich in diesen Logs offensichtlicher als in denen Ihres MCP-Clients.

CVE-2025-6514

Beliebteste