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