@proxycept/mcp — stdio-Brücke zu einem Proxycept MCP-Server

Eine dünne stdio↔HTTP-Brücke. Sie führt einen Model Context Protocol-Server auf stdio aus und leitet jede JSON-RPC-Nachricht unverändert an einen Proxycept MCP-Endpunkt (standardmäßig https://proxycept.com/api/mcp) mit Ihrem API-Token als Bearer-Header weiter.

Die meisten Menschen benötigen dieses Paket nicht. Der Proxycept MCP-Server ist ein gehosteter HTTP-Server — Claude Desktop und Cursor können sich mit einer URL und einem Authorization-Header verbinden, ohne Installation. Dieses Paket existiert für MCP-Clients, die nur stdio sprechen, und weil npx das Installations-Idiom ist, das Verzeichnislisten erwarten.

Für den installationsfreien Pfad, den Tool-Katalog und das Sicherheitsmodell siehe proxycept.com/docs → „Connect Claude or Cursor“, oder docs/user-manual.md §14. Unter Einstellungen → API-Token finden Sie die gleiche Konfiguration, die Sie kopieren können, adressiert an diese Bereitstellung und mit dem von Ihnen gewählten Token-Namen — der Token-Wert wird nur einmal angezeigt, bei der Erstellung, daher enthält der Block einen Platzhalter, den Sie ersetzen.

Was es nicht ist

Es enthält keine Tool-Liste, keine Tool-Schemata und keine Proxycept-spezifische Logik. tools/list wird vom Server beantwortet, nicht von diesem Paket. Das ist beabsichtigt: Der Server ist die einzige Quelle der Wahrheit für den Tool-Katalog, sodass ein hinzugefügtes oder geändertes Tool serverseitig keine Veröffentlichung hier erfordert und es keine Versionsabweichung zu unterstützen gibt. Wenn Sie dies lesen, weil Sie einen Spezialfall für einen Tool-Namen hinzufügen möchten, dann läuft das Design falsch.

Voraussetzungen

• Node.js 20 oder neuer (node --version).

• Ein Proxycept-API-Token (prx_live_…) — Einstellungen → API-Token unter proxycept.com/settings.

Verwenden Sie einen schreibgeschützten Token

Erstellen Sie den Token als schreibgeschützt. Dies ist die Standardeinstellung und die Sicherheitsgrenze, kein Vorschlag.

Die Lese-Tools von Proxycept geben erfassten HTTP-Verkehr zurück — Inhalte, die Ihr Konto nicht erstellt hat. Ein bösartiger Antworttext von einem vorgelagerten Dienst kann für ein Modell wie eine Anweisung wirken („Prompt Injection“). Einfach gesagt:

Ein read_write MCP-Token bedeutet, dass alles, was Ihr Proxy erfasst, Ihre Proxycept-Konfiguration beschreiben kann.

Ein Antworttext von einem fremden Server, der wie eine Anweisung geschrieben ist, wird zu einer Mock-Route, einem Abfangmuster oder einem gestoppten Profil in Ihrem Konto. Ein schreibgeschützter Token macht diese Kette innerhalb von Proxycept unvollständig: Es gibt nichts, was eine eingeschleuste Anweisung aufrufen könnte.

Behandeln Sie alles, was ein Proxycept-Tool zurückgibt, als nicht vertrauenswürdige Daten, nicht als Anweisungen — insbesondere, wenn Sie andere MCP-Server angeschlossen haben, die URLs abrufen, Shells ausführen oder Dateien schreiben können.

Wenn Sie wirklich Lese-/Schreibzugriff möchten

Nur für einen Client, mit dem Sie bewusst Ihre Einrichtung ändern lassen. Dann alle folgenden Punkte:

1. Erstellen Sie einen separaten Token (stufen Sie den Token, mit dem Sie Verkehr lesen, nicht hoch).

2. Aktivieren Sie niemals „immer erlauben“ für Proxycept-Tool-Aufrufe in Ihrem Client.

3. Verwenden Sie ihn nicht in derselben Sitzung, in der Sie erfassten Verkehr lesen — das ist genau die Kombination, die eine eingeschleuste Anweisung ausführbar macht.

Eine Sache, die ein Lese-/Schreib-Token dennoch nicht kann: eine erfasste Anfrage wiederholen. replay_flow sendet eine echte Anfrage mit den erfassten Anmeldeinformationen an einen Dritten, daher ist eine menschliche Genehmigung in der Proxycept-Webkonsole erforderlich (Einstellungen → Verbinden Sie Ihren KI-Client). Ihr KI-Client kann seine eigene Wiederholung nicht genehmigen, unabhängig davon, welchen Token er besitzt.

Konfigurieren Sie es — setzen Sie den Token in die Umgebung, nicht in die Konfigurationsdatei

Die Konfiguration Ihres MCP-Clients ist Klartext-JSON auf der Festplatte, oft in einem Verzeichnis, das mit Cloud-Speicher synchronisiert wird. Ein dort eingefügter prx_live_…-Token ist eine langlebige Anmeldeinformation in einem Backup, an das Sie nicht gedacht haben. Bevorzugen Sie die Umgebung.

Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) und die meisten anderen Clients verwenden die gleiche Form:

{
  "mcpServers": {
    "proxycept": {
      "command": "npx",
      "args": ["-y", "@proxycept/mcp"],
      "env": {
        // Read from your shell environment; the secret itself stays out of this file.
        "PROXYCEPT_API_TOKEN": "${PROXYCEPT_API_TOKEN}"
      }
    }
  }
}

Nicht jeder Client expandiert ${VAR} in seiner Konfiguration. Wenn Ihres dies nicht tut, ist die nächstbeste Option, die Variable zu exportieren, wo der Client sie erben wird (ein Login-Shell-Profil, launchctl setenv unter macOS, das systemd-Unit unter Linux) und den env-Block ganz wegzulassen — die Brücke liest PROXYCEPT_API_TOKEN aus ihrer geerbten Umgebung. Das Einfügen des wörtlichen Tokens in die Konfigurationsdatei funktioniert und ist die Option, die man zuletzt wählen sollte.

--token in der Befehlszeile wird unterstützt, ist aber nicht empfohlen: Ein Argument ist für jeden Prozess auf dem Rechner über die Prozessliste sichtbar.

Umgebungsvariablen

Jede Variable hat ein passendes Flag (--base-url, --url, --token, --timeout, --verbose).

Selbst gehostet

PROXYCEPT_BASE_URL=https://proxy.internal.example PROXYCEPT_API_TOKEN=… npx -y @proxycept/mcp

Klartext http:// wird für alles außer Loopback verweigert, sodass der Token niemals einen Klartext-Hop überqueren kann. Dieses Paket bietet kein Flag, um die TLS-Überprüfung zu deaktivieren und wird dies auch nicht tun.

Node selbst hat eines — NODE_TLS_REJECT_UNAUTHORIZED=0 schaltet die Zertifikatsüberprüfung für den gesamten Prozess aus — und die Brücke weigert sich zu starten, wenn dies für einen Nicht-Loopback-Endpunkt gesetzt ist, anstatt es stillschweigend zu übernehmen. Wenn Sie auf diesen Fehler stoßen, entfernen Sie die Variable (überprüfen Sie Ihr Shell-Profil und den env-Block Ihres MCP-Clients); es ist fast immer ein Überbleibsel vom Debuggen von etwas anderem, und wenn es gesetzt ist, würde Ihr Token über eine Verbindung gehen, die jeder auf dem Pfad lesen kann.

Überprüfen Sie Ihre Einrichtung

PROXYCEPT_API_TOKEN=prx_live_… npx -y @proxycept/mcp --check

Es führt einen echten MCP-Handshake und ein echtes tools/list durch und gibt dann aus, was der Server gesagt hat:

endpoint: https://proxycept.com/api/mcp
server:   proxycept 1.0.0 (MCP 2025-06-18)
tools:    20 — list_workspaces, list_profiles, …
ok

Die Tool-Anzahl kommt vom Server, nicht von diesem Paket, sodass sie sich ohne eine Veröffentlichung hier ändert. Schreib-Tools werden jedem Client aufgelistet und auf der API-Ebene verweigert, es sei denn, der Token ist read_write — siehe unten.

Exit-Codes: 0 ok · 1 Server nicht erreichbar oder Authentifizierung fehlgeschlagen · 2 Fehlerhafte Konfiguration.

Wenn etwas nicht stimmt

Sicherheitseigenschaften

• Der Token wird als Authorization: Bearer … an den konfigurierten Ursprung und nirgendwo anders gesendet. Eine Weiterleitung an einen anderen Ursprung wird verweigert, nicht verfolgt — die Anmeldeinformation wird niemals an einen Host übergeben, den Sie nicht konfiguriert haben. Gleichartige 307/308-Weiterleitungen werden verfolgt (bis zu 3 Hops), da die Beibehaltung von Ursprung und Methode bedeutet, dass das erneute Senden der Anmeldeinformation nichts daran ändert, wer sie erhält, und Reverse-Proxys geben sie durchaus aus; 301/302/303 wird verweigert, da das Wiederholen eines POST als GET Ihre Anfrage stillschweigend fallen lassen würde. (Der gehostete Server leitet niemals weiter.)

• Der Token wird niemals protokolliert und niemals an Ihren Client zurückgegeben. Jede Zeile, die nach stderr geschrieben wird, und jede Fehlermeldung, die diese Brücke für stdout synthetisiert, durchläuft einen Schwärzer, der das konfigurierte Geheimnis, alles, was wie ein prx_…-Token aussieht, und jede Bearer …-Zeichenfolge entfernt — auch im --verbose-Modus und einschließlich einer Anmeldeinformation, die ein Server in einem 4xx/5xx-Textkörper zurückgibt. Dieser letzte Fall ist wichtig, weil stdout Ihr MCP-Client ist: Es landet im Kontext des Modells und in den Protokollen des Clients. Stack-Traces werden niemals ausgegeben. Es gibt einen Test für jeden dieser Fälle.

• Der Protokollstrom wird niemals umgeschrieben. Die Schwärzung gilt für Nachrichten, die diese Brücke erstellt, nicht für die eigenen JSON-RPC-Nutzlasten des Servers — deren Verfälschung würde den Verkehr beschädigen, den Sie debuggen. Die Schwärzung von erfasstem Verkehr ist die Aufgabe des Servers (er wendet seine Maskierungs-Ausschlusslisten auf dem Lesepfad an).

• Es wird nichts auf die Festplatte geschrieben. Kein Cache, keine Konfigurationsdatei, kein Anmeldeinformationsspeicher.

• stdout transportiert nur Protokollnachrichten; alle Diagnosen gehen nach stderr.

• Null Laufzeitabhängigkeiten. npm ls --omit=dev für dieses Paket ist leer — die einzige Lieferkette ist Node selbst.

Entwicklung

cd clients/mcp
npm ci
npm test          # builds, then runs the suite against a fake JSON-RPC server
npm run typecheck

npm run check-package   # asserts the tarball ships every module, the bin, README and LICENSE

Aufbau: src/config.ts (Auflösung + Validierung der Konfiguration), src/redact.ts (Schwärzung + der einzige Logger), src/http.ts (ein POST pro Nachricht; SSE, Weiterleitungsrichtlinie, HTTP→JSON-RPC-Fehlerzuordnung), src/bridge.ts (die generische Weiterleitungsschleife), src/stdio.ts (Newline-getrennte JSON-Rahmung), src/cli.ts (Argumente, --check, Verdrahtung).

Verifiziert gegen einen gefälschten Server

Die Suite läuft gegen einen gefälschten JSON-RPC-HTTP-Server in test/helpers.js: wortgetreue Weiterleitung (einschließlich Methoden, von denen dieses Paket noch nie gehört hat), Header-Form, Mcp-Session-Id und Protokollversion-Echo, SSE-Streaming, 202-Benachrichtigungen, HTTP→MCP-Fehlerzuordnung, Batch-Verarbeitung, die Weiterleitungsrichtlinie, Sitzungsablauf, NDJSON-Rahmung über Chunk-Grenzen hinweg und die Abwesenheit des Tokens in der gesamten Ausgabe.

Verifiziert gegen einen echten Proxycept

--check wurde Ende-zu-Ende gegen eine echte Control-API mit aktiviertem MCP-Server ausgeführt (V4-T66): echte initialize-Fähigkeitsverhandlung, ein echtes tools/list (20 Tools), mit einem schreibgeschützten prx_live_-Token. Die verbleibenden Unbekannten sind produktionsspezifisch — ob die gehostete Bereitstellung ein Mcp-Session-Id ausgibt, ob ein langer Tool-Aufruf als JSON oder SSE zurückkommt und der genaue Wortlaut seiner 401/403/429-Textkörper. Die Brücke ist generisch, sodass jeder dieser Punkte ohne eine Codeänderung hier abweichen kann; der Live-Test gegen https://proxycept.com ist Schritt 5 von PUBLISHING.md.

Veröffentlichung (Betreuer)

Veröffentlichungen sind bewusst manuell — es gibt absichtlich keinen CI-Job, der veröffentlicht, sodass ein kompromittierter Workflow-Token kein Paket ausliefern kann, das Kundenanmeldedaten verarbeitet. Das vollständige Runbook (Organisationserstellung, Preflight, die genaue npm publish --access public-Sequenz, Verifizierung und der Deprecate-Pfad) befindet sich in PUBLISHING.md in diesem Verzeichnis. Es ist nicht Teil des veröffentlichten Tarballs.