Verbinden von MCP-Clients mit dem PipesHub MCP-Server

Dieser Leitfaden behandelt, wie Sie den entfernten MCP-Server von PipesHub mit Cursor, Claude Code, Gemini CLI, Codex CLI, Claude.ai (Web) und LibreChat über statische OAuth-Anmeldedaten oder Bearer-Tokens verbinden.

PipesHub stellt einen entfernten MCP-Endpunkt über Streamable HTTP unter /mcp bereit. MCP-Clients verbinden sich direkt mit diesem Endpunkt – ohne lokale npm-Pakete oder stdio-Prozesse.

Coding-Agent? Beginnen Sie bei Für Coding-Agents. Installieren Sie die Skill in das Benutzer-Repository mit npx skills add pipeshub-ai/mcp-server (siehe skills/pipeshub). Mitwirkende, die in diesem Repository arbeiten: Lesen Sie AGENTS.md.

Auf der Suche nach der Tool-Referenz? Siehe TOOLS.md für Beschreibungen, Argumente und einen Entscheidungsleitfaden für jedes Tool, das der MCP-Server bereitstellt (pipeshub_chat, pipeshub_search, pipeshub_get_record_content, pipeshub_download_record, pipeshub_directory, pipeshub_sources, pipeshub_agents).

Verwenden Sie QM? QM kann keinen Drittanbieter-MCP-Endpunkt anhängen – es ist ein MCP-Server für seine eigene Umgebung, kein Client. Folgen Sie PipesHub mit QM verwenden. Das Bereitstellungsschicht-Bundle in qm/ gibt Agents einen pipeshub-Befehl in ihrer Sandbox; dieses Paket liefert diesen Befehl als zweites Bin.

Voraussetzungen

• Eine laufende PipesHub-Instanz (selbst gehostet oder in der Cloud)

• Eine in PipesHub erstellte OAuth-App (siehe Schritt 1)

Related MCP server: Rocket.Chat MCP Server

Schritt 1: Erstellen Sie eine OAuth-App in PipesHub

1. Melden Sie sich als Administrator bei Ihrer PipesHub-Instanz an

2. Navigieren Sie zu Einstellungen > Entwicklereinstellungen > OAuth-Apps

3. Klicken Sie auf OAuth-App erstellen

4. Füllen Sie die App-Details aus:

   • Name: z. B. MCP-Integration

   • Redirect-URIs: Fügen Sie alle Redirect-URIs für die Clients hinzu, die Sie verwenden möchten:

     Client	Redirect-URI
     Cursor	cursor://anysphere.cursor-mcp/oauth/callback
     Claude Code	http://localhost:<PORT>/callback (z. B. http://localhost:8080/callback)
     Claude.ai (Web)	https://claude.ai/api/mcp/auth_callback
     Gemini CLI	http://localhost:7777/oauth/callback
     LibreChat	http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

Wichtig: Die Bereiche in MCP_SCOPES müssen mit den Bereichen übereinstimmen, die Ihrer OAuth-App gewährt wurden – eine Abweichung führt zu einem Autorisierungsfehler.

5. Speichern Sie die App und kopieren Sie die Client-ID und das Client-Secret

Anpassen der Standard-Bereiche

Standardmäßig stellt PipesHub einige Standard-Bereiche in seinem /.well-known/oauth-protected-resource/mcp-Discovery-Endpunkt bereit. Sie können anpassen, welche Bereiche verfügbar sind, indem Sie die Umgebungsvariable MCP_SCOPES auf Ihrer PipesHub-Instanz setzen. Dies ist nützlich für Clients wie Claude Code, die automatisch alle verfügbaren Bereiche anfordern.

Platzhalter

Ersetzen Sie diese in allen folgenden Konfigurationen:

Die entfernte MCP-Endpunkt-URL lautet: PIPESHUB_INSTANCE_URL/mcp

Remote-MCP-Einrichtung

Cursor unterstützt statisches OAuth für entfernte MCP-Server über das auth-Objekt in mcp.json.

Konfiguration

Öffnen Sie Cursor-Einstellungen > Tools und Integrationen > Neuer MCP-Server, oder bearbeiten Sie die .cursor/mcp.json Ihres Projekts:

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "auth": {
        "CLIENT_ID": "YOUR_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

Cursor erkennt die Autorisierungs- und Token-Endpunkte automatisch über die Metadaten von PipesHubs /.well-known/oauth-protected-resource/mcp.

Hinweis: Wenn das Feld scopes weggelassen wird, ruft Cursor /.well-known/oauth-protected-resource/mcp ab und fordert alle dort aufgeführten scopes_supported an. Um den Zugriff einzuschränken, listen Sie explizit nur die Bereiche auf, die Sie benötigen. Sie können auch serverseitig steuern, welche Bereiche verfügbar sind – siehe Anpassen der Standard-Bereiche.

Verwenden von Umgebungsvariablen

Verwenden Sie Cursors ${env:VAR}-Interpolation, um Geheimnisse aus Konfigurationsdateien herauszuhalten:

{
  "mcpServers": {
    "pipeshub": {
      "url": "${env:PIPESHUB_INSTANCE_URL}/mcp",
      "auth": {
        "CLIENT_ID": "${env:PIPESHUB_CLIENT_ID}",
        "CLIENT_SECRET": "${env:PIPESHUB_CLIENT_SECRET}",
        "scopes": [
          "kb:read", "kb:write",
          "semantic:read", "semantic:write",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write",
          "config:read", "user:read"
        ]
      }
    }
  }
}

Redirect-URI

Cursor verwendet eine feste Redirect-URI für alle MCP-Server:

cursor://anysphere.cursor-mcp/oauth/callback

Registrieren Sie diese als zulässige Redirect-URI, wenn Sie die OAuth-App in PipesHub erstellen.

Fehlerbehebung beim OAuth-Login

Wenn der interne Browser von Cursor die OAuth-Loginseite nicht lädt, kopieren Sie die Autorisierungs-URL aus dem internen Browser und fügen Sie sie in Ihren normalen Browser ein, um den Login-Vorgang abzuschließen.

Claude Code unterstützt entfernte HTTP-MCP-Server mit statischen OAuth-Anmeldedaten über --client-id, --client-secret und --callback-port.

PipesHub stellt die Discovery unter /.well-known/oauth-protected-resource/mcp bereit, sodass Claude Code die Autorisierungs- und Token-Endpunkte automatisch erkennt.

Wichtig: Claude Code unterstützt keine Konfiguration bestimmter Bereiche. Es ruft /.well-known/oauth-protected-resource/mcp ab, liest die Liste scopes_supported und fordert alle davon an. Ihre OAuth-App in PipesHub muss Zugriff auf alle Bereiche haben, die im Discovery-Endpunkt aufgeführt sind, andernfalls schlägt die Autorisierungsanfrage fehl. Um die verfügbaren Bereiche einzuschränken, siehe Anpassen der Standard-Bereiche.

Mit CLI hinzufügen

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

--client-secret ohne Wert fordert zur maskierten Eingabe auf. Um die Eingabeaufforderung zu überspringen, setzen Sie die Umgebungsvariable MCP_CLIENT_SECRET:

MCP_CLIENT_SECRET=YOUR_CLIENT_SECRET claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

Um es für alle Projekte verfügbar zu machen:

claude mcp add --transport http --scope user \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

Mit JSON hinzufügen

claude mcp add-json pipeshub '{
  "type": "http",
  "url": "PIPESHUB_INSTANCE_URL/mcp",
  "oauth": {
    "clientId": "YOUR_CLIENT_ID",
    "callbackPort": 8080
  }
}' --client-secret

Projektspezifisch (.mcp.json)

Erstellen Sie eine Datei .mcp.json im Stammverzeichnis Ihres Projekts. Diese kann in die Versionskontrolle eingecheckt werden (Geheimnisse bleiben über Umgebungsvariablen außen vor):

{
  "mcpServers": {
    "pipeshub": {
      "type": "http",
      "url": "${PIPESHUB_INSTANCE_URL}/mcp",
      "oauth": {
        "clientId": "${PIPESHUB_CLIENT_ID}",
        "callbackPort": 8080
      }
    }
  }
}

Setzen Sie die Umgebungsvariablen, bevor Sie Claude Code starten:

export PIPESHUB_INSTANCE_URL="https://app.pipeshub.com"
export PIPESHUB_CLIENT_ID="your-client-id"

Hinweis: Das Client-Secret wird im System-Schlüsselbund gespeichert, nicht in Konfigurationsdateien. Sie werden beim ersten Authentifizieren über /mcp zur Eingabe aufgefordert.

Authentifizieren

Nach dem Hinzufügen des Servers führen Sie /mcp in Claude Code aus und folgen dem Browser-Login-Vorgang. Tokens werden sicher gespeichert und automatisch aktualisiert.

Überprüfen

claude mcp list
claude mcp get pipeshub

Gemini CLI unterstützt entfernte MCP-Server mit OAuth über dynamic_discovery (die Standardeinstellung), das Autorisierungs- und Token-Endpunkte automatisch aus PipesHubs /.well-known/oauth-protected-resource/mcp erkennt.

Option A: Einstellungsdatei

Bearbeiten Sie ~/.gemini/settings.json:

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "oauth": {
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

Hinweis: Passen Sie die scopes-Liste an die Bereiche an, die Ihrer OAuth-App gewährt wurden. Wenn Sie nur eine Teilmenge der Tools benötigen, können Sie die Bereiche entsprechend einschränken.

Option B: CLI-Befehl

gemini mcp add --transport http pipeshub PIPESHUB_INSTANCE_URL/mcp

Bearbeiten Sie dann ~/.gemini/settings.json, um den oauth-Block wie oben gezeigt hinzuzufügen.

Authentifizieren

Verwenden Sie in Gemini CLI die /mcp auth-Befehle:

# List servers and their auth status
/mcp auth

# Authenticate with PipesHub (opens browser for login)
/mcp auth pipeshub

# Re-authenticate if tokens expire
/mcp auth pipeshub

Bei der ersten Verbindung erkennt Gemini automatisch die 401-Antwort, entdeckt die OAuth-Endpunkte und öffnet einen Browser für den Login. Tokens werden sicher in ~/.gemini/mcp-oauth-tokens.json gespeichert und automatisch aktualisiert.

Server verwalten

# List all configured servers
gemini mcp list

# Remove the server
gemini mcp remove pipeshub

# Temporarily disable/enable
gemini mcp disable pipeshub
gemini mcp enable pipeshub

OAuth-Konfigurationseigenschaften

Hinweis: OAuth erfordert einen lokalen Browser. Es funktioniert nicht in headless Umgebungen, bei Remote-SSH ohne X11-Weiterleitung oder in Containern ohne Browserzugriff.

Codex CLI (OpenAI Codex) verbindet sich über Streamable HTTP mit entfernten MCP-Servern, konfiguriert mit einer [mcp_servers.<name>]-Tabelle in ~/.codex/config.toml (oder .codex/config.toml im Projektstamm, um es pro Projekt zu begrenzen). Der HTTP-Transport von Codex authentifiziert sich mit einem Bearer-Token, das aus einer Umgebungsvariable gelesen wird. Übergeben Sie daher ein PipesHub-JWT-Bearer-Token.

[mcp_servers.pipeshub]
url = "PIPESHUB_INSTANCE_URL/mcp"
bearer_token_env_var = "PIPESHUB_BEARER_TOKEN"

bearer_token_env_var ist der Name der Umgebungsvariable, die das Token enthält – exportieren Sie sie, bevor Sie Codex starten:

export PIPESHUB_BEARER_TOKEN="YOUR_BEARER_TOKEN"

Das Token ist das rohe JWT ohne das Schlüsselwort Bearer.

Oder fügen Sie es mit der CLI hinzu:

codex mcp add pipeshub \
  --url PIPESHUB_INSTANCE_URL/mcp \
  --bearer-token-env-var PIPESHUB_BEARER_TOKEN

--bearer-token-env-var akzeptiert den Namen der Umgebungsvariable, die das Token enthält, nicht den Token-Wert selbst.

Überprüfen

# List configured MCP servers
codex mcp list

# Inside the Codex TUI, view server status and available tools
/mcp

Claude.ai unterstützt benutzerdefinierte Konnektoren über entfernte MCP-Server. Damit können Sie PipesHub-Tools direkt in der Claude.ai-Weboberfläche verwenden, ohne lokale Einrichtung.

Hinweis: Diese Funktion befindet sich derzeit in der Beta-Phase. Benutzer des kostenlosen Plans sind auf einen benutzerdefinierten Konnektor beschränkt.

Für einzelne Benutzer (Pro-/Max-Pläne)

1. Gehen Sie zu claude.ai und navigieren Sie zu Einstellungen > Konnektoren

2. Klicken Sie unten im Abschnitt „Konnektoren“ auf Benutzerdefinierten Konnektor hinzufügen

3. Geben Sie die MCP-Server-URL ein:

   PIPESHUB_INSTANCE_URL/mcp

4. Klicken Sie auf Erweiterte Einstellungen und geben Sie Ihre OAuth-Anmeldedaten ein:

   • OAuth-Client-ID: YOUR_CLIENT_ID

   • OAuth-Client-Secret: YOUR_CLIENT_SECRET

5. Klicken Sie auf Hinzufügen

6. Sie werden zur Login-Seite von PipesHub weitergeleitet, um sich zu authentifizieren und Berechtigungen zu erteilen

7. Nach der Authentifizierung ist der Konnektor aktiv und PipesHub-Tools sind in Ihren Claude.ai-Unterhaltungen verfügbar

Für Team-/Enterprise-Pläne

Organisationsinhaber müssen zuerst den Konnektor hinzufügen:

1. Navigieren Sie zu Organisationseinstellungen > Konnektoren

2. Klicken Sie auf Benutzerdefinierten Konnektor hinzufügen

3. Geben Sie die MCP-Server-URL ein: PIPESHUB_INSTANCE_URL/mcp

4. Klicken Sie auf Erweiterte Einstellungen und geben Sie die OAuth-Client-ID und das Client-Secret ein

5. Klicken Sie auf Hinzufügen

Teammitglieder können sich dann verbinden:

1. Gehen Sie zu Einstellungen > Konnektoren

2. Suchen Sie den PipesHub-Konnektor (mit dem Label „Benutzerdefiniert“)

3. Klicken Sie auf Verbinden, um sich über den OAuth-Login von PipesHub zu authentifizieren

Redirect-URI

Claude.ai verwendet die folgende Redirect-URI für OAuth:

https://claude.ai/api/mcp/auth_callback

Registrieren Sie diese als zulässige Redirect-URI in Ihrer PipesHub-OAuth-App.

Sicherheitshinweise

• Verbinden Sie sich nur mit vertrauenswürdigen MCP-Servern

• Überprüfen Sie die während des OAuth-Authentifizierungsvorgangs angeforderten Berechtigungen

• Claude.ai interagiert in Ihrem Namen mit PipesHub unter Verwendung des gewährten OAuth-Tokens – Ihr Passwort wird niemals weitergegeben

LibreChat unterstützt entfernte MCP-Server mit OAuth-Authentifizierung über seine Benutzeroberfläche für benutzerdefinierte Konnektoren. Damit können Sie PipesHub-Tools mit jedem in Ihrer LibreChat-Instanz verfügbaren Modell verbinden.

Konfiguration

1. Melden Sie sich bei Ihrer LibreChat-Instanz an

2. Navigieren Sie zum Einstellungsbereich MCP-Server

3. Klicken Sie auf Hinzufügen, um einen neuen benutzerdefinierten MCP-Connector zu erstellen

4. Füllen Sie die Connector-Details aus:

   • Name: Pipeshub (oder ein beliebiger Name Ihrer Wahl)

   • MCP-Server-URL: PIPESHUB_INSTANCE_URL/mcp

   • Transport: Wählen Sie Streamable HTTPS

   • Authentifizierung: Wählen Sie OAuth

5. Geben Sie Ihre OAuth-Anmeldedaten ein:

   • Client-ID: YOUR_CLIENT_ID

   • Client-Secret: YOUR_CLIENT_SECRET

   • Autorisierungs-URL: PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

   • Token-URL: PIPESHUB_INSTANCE_URL/api/v1/oauth2/token

   • Scope: openid email (oder zusätzliche Scopes nach Bedarf)

6. Aktivieren Sie Ich vertraue dieser Anwendung

7. Klicken Sie auf Hinzufügen, um den Connector zu speichern

8. Nach dem Hinzufügen generiert LibreChat eine Redirect-URI, die im Einstellungsbereich des Connectors angezeigt wird (neben der Kopieren-Schaltfläche). Sie folgt diesem Format:

   http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

9. Kopieren Sie die Redirect-URI und registrieren Sie sie als zulässige Redirect-URI in Ihrer PipesHub-OAuth-App (siehe Schritt 1)

10. Kehren Sie zum LibreChat-Connector zurück und klicken Sie auf Aktualisieren, um den OAuth-Flow zu starten – Sie werden zur PipesHub-Anmeldeseite weitergeleitet, um sich zu authentifizieren und Berechtigungen zu erteilen

Redirect-URI

LibreChat generiert die Redirect-URI nachdem der Connector erstellt wurde. Die URI folgt diesem Format:

http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

Wobei <server-identifier> die eindeutige Kennung ist, die von LibreChat zugewiesen wird (sichtbar oben in den Connector-Einstellungen als „Unique Server Identifier"). Sie müssen diese URI kopieren und vor der Authentifizierung zu den zulässigen Redirect-URIs Ihrer PipesHub-OAuth-App hinzufügen.

Hinweis: Wenn Ihre LibreChat-Instanz auf einem anderen Host oder Port läuft, spiegelt die URI dies wider (z. B. https://chat.example.com/api/mcp/pipeshub/oauth/callback).

Scopes

LibreChat ermöglicht es Ihnen, die OAuth-Scopes im Feld Scope anzugeben. Verwenden Sie eine durch Leerzeichen getrennte Liste:

openid email

Um PipesHub-spezifische Scopes anzufordern, fügen Sie sie dem Scope-Feld hinzu:

openid email org:read kb:read kb:write semantic:read conversation:read conversation:write conversation:chat agent:read agent:execute

Hinweis: Die von Ihnen angeforderten Scopes müssen mit den Scopes übereinstimmen, die Ihrer OAuth-App in PipesHub gewährt wurden. Einzelheiten finden Sie unter Anpassen der Standard-Scopes.

Lokaler MCP-Server (Stdio)

Statt eine Verbindung zum entfernten MCP-Endpunkt von PipesHub herzustellen, können Sie den MCP-Server lokal als Stdio-Prozess mit dem npm-Paket @pipeshub-ai/mcp ausführen. Dies ist nützlich, wenn Sie ein lokales Setup bevorzugen oder in Umgebungen arbeiten müssen, in denen direkte HTTP-Verbindungen zum entfernten MCP-Endpunkt nicht praktikabel sind.

Voraussetzungen

• Node.js 18+ installiert

• Eine PipesHub-Instanz-URL

• Authentifizierungsdaten: entweder ein Bearer-Token (JWT) oder OAuth-Client-ID + Secret

Platzhalter

Ersetzen Sie diese in allen folgenden Konfigurationen:

Konfigurieren Sie in den Claude-Desktop-Einstellungen (claude_desktop_config.json):

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Mit OAuth-Anmeldedaten:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET",
        "--token-url",
        "/api/v1/oauth2/token"
      ]
    }
  }
}

Öffnen Sie Cursor-Einstellungen > Tools und Integrationen > Neuer MCP-Server, oder bearbeiten Sie die Datei .cursor/mcp.json Ihres Projekts:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Mit OAuth-Anmeldedaten:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET",
        "--token-url",
        "/api/v1/oauth2/token"
      ]
    }
  }
}

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

Mit OAuth-Anmeldedaten:

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

Mit OAuth-Anmeldedaten:

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

Führen Sie den MCP-Server als lokalen Stdio-Prozess aus, authentifiziert mit der Client-ID und dem Secret einer OAuth-App (der client_credentials-Grant). Bearbeiten Sie ~/.codex/config.toml (oder .codex/config.toml im Projektstammverzeichnis):

[mcp_servers.pipeshub]
command = "npx"
args = [
  "-y",
  "@pipeshub-ai/mcp",
  "start",
  "--server-url",
  "PIPESHUB_INSTANCE_URL/api/v1",
  "--client-id",
  "YOUR_CLIENT_ID",
  "--client-secret",
  "YOUR_CLIENT_SECRET",
  "--token-url",
  "/api/v1/oauth2/token",
]

Hinweise:

• --server-url muss /api/v1 enthalten.

• --token-url /api/v1/oauth2/token ist erforderlich.

Oder authentifizieren Sie sich stattdessen mit einem JWT-Bearer-Token:

[mcp_servers.pipeshub]
command = "npx"
args = [
  "-y",
  "@pipeshub-ai/mcp",
  "start",
  "--server-url",
  "PIPESHUB_INSTANCE_URL/api/v1",
  "--bearer-auth",
  "YOUR_BEARER_TOKEN",
]

Öffnen Sie die Befehlspalette > MCP: Open User Configuration und fügen Sie dann hinzu:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Öffnen Sie Windsurf-Einstellungen > Cascade > MCPs verwalten > Rohe Konfiguration anzeigen und fügen Sie dann hinzu:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Um den lokalen MCP-Server aus einem geklonten Repository statt aus dem npm-Paket auszuführen:

git clone https://github.com/pipeshub-ai/pipeshub-ai.git
cd pipeshub-ai
npm install
npm run build
node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

Ersetzen Sie für die MCP-Client-Konfiguration npx @pipeshub-ai/mcp durch node ./bin/mcp-server.js:

{
  "mcpServers": {
    "pipeshub": {
      "command": "node",
      "args": [
        "./bin/mcp-server.js",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Zum Debuggen mit MCP Inspector:

npx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

CLI-Hilfe

Für eine vollständige Liste der Server-Argumente:

npx @pipeshub-ai/mcp --help

So funktioniert es

Architektur

AI Client (Cursor / Claude Code / Gemini CLI / Codex CLI / Claude.ai / LibreChat)
        │
        │  HTTP POST (JSON-RPC)
        │  Authorization: Bearer <token>
        ▼
  PIPESHUB_INSTANCE_URL/mcp
        │
        │  StreamableHTTP Transport
        │  (stateless, per-request MCP server)
        ▼
  PipesHub API (curated tool set — see TOOLS.md)

OAuth-geschützte Ressourcenerkennung

PipesHub stellt die Erkennung OAuth-geschützter Ressourcen unter folgender Adresse bereit:

PIPESHUB_INSTANCE_URL/.well-known/oauth-protected-resource/mcp

Dies gibt automatisch alle OAuth-Endpunkte zurück:

• Autorisierung: PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

• Token: PIPESHUB_INSTANCE_URL/api/v1/oauth2/token

• Widerruf: PIPESHUB_INSTANCE_URL/api/v1/oauth2/revoke

• JWKS: PIPESHUB_INSTANCE_URL/.well-known/jwks.json

Fehlerbehebung

„Incompatible auth server: does not support dynamic client registration"

Dies bedeutet, dass der Client eine dynamische Registrierung versucht, anstatt Ihre vorkonfigurierten Anmeldedaten zu verwenden. Stellen Sie sicher, dass Sie --client-id und --client-secret (Claude Code) oder das auth-Objekt (Cursor) korrekt übergeben haben.

Authentifizierung schlägt fehl / Weiterleitungsfehler

• Stellen Sie sicher, dass die Redirect-URI in Ihrer OAuth-App exakt mit der vom Client verwendeten übereinstimmt:

  • Cursor: cursor://anysphere.cursor-mcp/oauth/callback

  • Claude Code: http://localhost:<callbackPort>/callback

  • Claude.ai: https://claude.ai/api/mcp/auth_callback

  • Gemini CLI: http://localhost:7777/oauth/callback

  • LibreChat: http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

• Stellen Sie sicher, dass die OAuth-App in PipesHub aktiv ist (nicht gesperrt)

MCP-Endpunkt nicht erreichbar

• Überprüfen Sie, ob der Endpunkt erreichbar ist: curl -X POST PIPESHUB_INSTANCE_URL/mcp (sollte 401 zurückgeben, keinen Verbindungsfehler)

• Prüfen Sie, ob MCP in Ihrer PipesHub-Instanz aktiviert ist

Debugging mit MCP Inspector

npx @modelcontextprotocol/inspector

Verbinden Sie sich dann mit PIPESHUB_INSTANCE_URL/mcp mit einem Bearer-Token, um den Endpunkt direkt zu testen.

FAQ

1. Aktualisieren Sie die Umgebungsvariable MCP_SCOPES auf Ihrer PipesHub-Instanz, um die neuen Scopes einzuschließen, die Sie über den Erkennungsendpunkt verfügbar machen möchten.

2. Aktualisieren Sie die OAuth-App-Scopes in PipesHub: Gehen Sie zu Einstellungen > Entwicklereinstellungen > OAuth-Apps, wählen Sie Ihre OAuth-App aus und fügen Sie Scopes hinzu oder entfernen Sie sie nach Bedarf.

3. Authentifizieren Sie den Client erneut – vorhandene Token tragen die alten Scopes, daher müssen Sie sich erneut authentifizieren, um ein neues Token mit den aktualisierten Scopes zu erhalten. Zum Beispiel:

   • Cursor: Entfernen Sie den MCP-Server und fügen Sie ihn erneut hinzu, oder löschen Sie das zwischengespeicherte OAuth-Token und verbinden Sie sich erneut.

   • Claude Code: Führen Sie /mcp aus und schließen Sie den Browser-Anmeldevorgang erneut ab.

   • Gemini CLI: Führen Sie /mcp auth pipeshub aus, um sich erneut zu authentifizieren.

   • Codex CLI: Aktualisieren Sie PIPESHUB_BEARER_TOKEN mit einem neuen Token und starten Sie Codex neu.

   • Claude.ai: Trennen Sie den Connector in Einstellungen > Connectors und verbinden Sie ihn erneut.