Connecting MCP Clients to PipesHub MCP Server

This guide covers how to connect PipesHub's remote MCP server to Cursor, Claude Code, Gemini CLI, Codex CLI, Claude.ai (Web), and LibreChat using static OAuth credentials or bearer tokens.

PipesHub exposes a remote MCP endpoint over Streamable HTTP at /mcp. MCP Clients connect to this endpoint directly -- no local npm packages or stdio processes needed.

▶ Watch the 2½-minute demo: Claude Code using this MCP server to answer from Jira, Slack, GitHub and Drive, with each person's own permissions.

Coding agent? Start at For coding agents. Install the skill into the user's repo with npx skills add pipeshub-ai/mcp-server (see skills/pipeshub) and append the AGENTS.md snippet on that page. Listed on the official MCP registry as io.github.pipeshub-ai/mcp and on Cursor Directory as PipesHub. The listing files (plugin.json, mcp.json) default MCP to http://localhost:3000/mcp (Docker). Change the URL for a company instance; they contain no secrets. Contributors working in this repository: read AGENTS.md.

Claude Code plugin: /plugin marketplace add pipeshub-ai/mcp-server, then /plugin install pipeshub@pipeshub, adds the MCP server, the skill, and the /pipeshub:ask and /pipeshub:setup commands. It connects to ${PIPESHUB_MCP_URL:-https://app.pipeshub.com/mcp} with Authorization: Bearer ${PIPESHUB_MCP_TOKEN}; export both in your shell (self-hosted: set the URL to https://<your-instance>/mcp), then restart Claude Code.

Looking for the tool reference? See TOOLS.md for descriptions, arguments, and a decision guide for each tool the MCP server exposes (pipeshub_chat, pipeshub_search, pipeshub_get_record_content, pipeshub_download_record, pipeshub_directory, pipeshub_sources, pipeshub_agents). Searching and reading records is the recommended default; pipeshub_chat is optional (see Leaving pipeshub_chat out).

Using QM? QM cannot attach a third-party MCP endpoint — it is an MCP server to its own harness, not a client. Follow Use PipesHub with QM. The deployment-layer bundle in qm/ gives agents a pipeshub command inside their sandbox; this package ships that command as a second bin.

Prerequisites

• A running PipesHub instance: PipesHub Cloud or self-hosted. To self-host, the local Docker demo playbook covers install and first-run — do not scaffold LangChain. First-run (account + LLM) is still in the browser; search 500s until an LLM is configured.
• An OAuth app created in PipesHub (see Step 1)

Step 1: Create an OAuth App in PipesHub

1. Log in to your PipesHub instance as an admin
2. Navigate to Settings > Developer Settings > OAuth Apps
3. Click Create OAuth App
4. Fill in the app details:

   • Name: e.g., MCP Integration

   • Redirect URIs: Add all the redirect URIs for the clients you plan to use:

     Client	Redirect URI
     Cursor	cursor://anysphere.cursor-mcp/oauth/callback
     Claude Code	http://localhost:<PORT>/callback (e.g., 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

Important: Grant your OAuth app every scope the discovery endpoint lists (see Customizing Default Scopes). Sign-in grants the requested scopes the app allows and drops the rest, so a scope missing from the app does not fail the login; the tools that need it are refused. If the app allows none of the requested scopes, or a requested scope name is unknown, sign-in fails with invalid_scope.

5. Save the app and copy the Client ID and Client Secret

Customizing Default Scopes

The /.well-known/oauth-protected-resource/mcp discovery endpoint lists the scopes the MCP tools use, so clients like Claude Code, which request every listed scope, ask only for what the tools need:

Discovery also lists offline_access. It is not a tool scope: it lets the client get a refresh token, so it stays signed in instead of signing in again when its access token expires.

The list is limited to the MCP_SCOPES environment variable on your PipesHub instance, which is also the upper limit on the scopes any personal access token or OAuth token can hold. Remove a scope from MCP_SCOPES to stop discovery listing it. Clients that set their own scopes, such as Cursor and LibreChat, still request it, but PipesHub does not grant a scope that MCP_SCOPES excludes. PipesHub servers older than this behavior list all of MCP_SCOPES.

Placeholders

Replace these in all configurations below:

The remote MCP endpoint URL is: PIPESHUB_INSTANCE_URL/mcp

Remote MCP Setup

{
  "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"
        ]
      }
    }
  }
}

{
  "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"
        ]
      }
    }
  }
}

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

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

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

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

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

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

claude mcp list
claude mcp get pipeshub

{
  "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"
        ]
      }
    }
  }
}

gemini mcp add --transport http pipeshub PIPESHUB_INSTANCE_URL/mcp

# 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

# 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

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

export PIPESHUB_BEARER_TOKEN="YOUR_BEARER_TOKEN"

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

# List configured MCP servers
codex mcp list

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

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

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

openid email

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

Local MCP Server (Stdio)

Instead of connecting to PipesHub's remote MCP endpoint, you can run the MCP server locally as a stdio process using the @pipeshub-ai/mcp npm package. This is useful when you prefer a local setup or need to work in environments where direct HTTP connections to the remote MCP endpoint aren't practical.

Prerequisites

• Node.js 18+ installed
• A PipesHub instance URL
• A credential that acts as you, so results follow your permissions. Either:
  • No token in the config: run pipeshub login once (npm i -g @pipeshub-ai/mcp; --url <origin> when self-hosted). With no --bearer-auth, start uses that sign-in, refreshes it (on PipesHub versions that issue device-login refresh tokens; otherwise it lasts an hour), and defaults --server-url to the instance you signed in to. It also reads PIPESHUB_TOKEN from the environment, sent only to --server-url or PIPESHUB_BASE_URL.
  • A personal access token (phpat_…), minted in PipesHub under Developer Settings and passed as --bearer-auth, as in the examples below.

With pipeshub login, a Claude Desktop entry is just:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": ["@pipeshub-ai/mcp", "start"]
    }
  }
}

Placeholders

Replace these in all configurations below:

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

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

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

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

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

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

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

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

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

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

CLI Help

For a full list of server arguments:

npx @pipeshub-ai/mcp --help

Retries and Timeouts

The local server (start and serve) retries a PipesHub request that is refused with 429, 502, 503 or 504. It waits for as long as the Retry-After header asks, or, without one, backs off for half a second and then a second. It stops after three tries in all and passes the last answer on. A Retry-After of more than 30 seconds is not waited out: that answer is passed on at once, and the tool's error says how long PipesHub asked to wait. Only requests that are safe to repeat are retried (GET, HEAD, OPTIONS, PUT, DELETE). Search and chat are POSTs and are never retried, because a repeat would be a second search or a second answer.

A request that gets no response within 60 seconds is abandoned. The limit covers the wait for PipesHub to start answering, not the whole answer, so a long chat response that is already streaming is not cut off.

Both are set with environment variables, in the MCP client's env block or with --env NAME=VALUE:

Read-only mode

Two tools write: pipeshub_create_collection and pipeshub_upload add collections and documents (they never delete or overwrite). They need the kb:write and kb:upload scopes. To serve read tools only from the local server, pass --scope read to start or serve. On the remote /mcp, a token without those scopes is not offered the write tools.

Leaving pipeshub_chat out

The server offers all eleven tools, and its instructions and tool descriptions tell the agent to answer with pipeshub_search and pipeshub_get_record_content first. pipeshub_chat runs PipesHub's own assistant and is optional: for an agent that can call tools, it adds cost and time without adding accuracy. In PipesHub's evaluation (100 questions, Claude Opus as the agent), search and read alone found 88% of the facts at $0.54 and 78 seconds median per answer; adding chat also found 88%, at about $0.73 and 97 seconds. See TOOLS.md for the full figures.

Nothing changes unless you choose to: by default every tool stays. To hold an agent to search and read, leave pipeshub_chat out, together with pipeshub_agents, which only picks an agent for chat:

• Local stdio server: set PIPESHUB_MCP_CHAT=off in the server's env block in your MCP client config, or pass --env PIPESHUB_MCP_CHAT=off to start or serve. The server then mounts nine tools, and its instructions no longer mention chat or agents. Unset or on keeps today's behaviour; any other value stops the server with an error that says what it accepts.

  "env": { "PIPESHUB_MCP_CHAT": "off" }
  

  Copy

  To pick tools one by one instead, list the ones to keep with --tool (for example --tool pipeshub_search --tool pipeshub_get_record_content). --tool does not change the instructions.

• Remote endpoint (/mcp): turn the tool off in the client. In Claude Code, run claude --disallowedTools "mcp__pipeshub__pipeshub_chat,mcp__pipeshub__pipeshub_agents", where pipeshub is the name you gave the server, or put the same entries in the permissions.deny list of .claude/settings.json. In other clients, use the per-tool toggles in their MCP settings, where they offer them.

Keep pipeshub_chat when the client cannot run its own tool loop, when you want PipesHub's assistant to write the answer, to talk to a configured PipesHub agent, or to take an action through the user's connected tools.

How It Works

Architecture

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 Protected Resource Discovery

PipesHub exposes OAuth protected resource discovery at:

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

This returns all OAuth endpoints automatically:

• Authorization: PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize
• Token: PIPESHUB_INSTANCE_URL/api/v1/oauth2/token
• Revocation: PIPESHUB_INSTANCE_URL/api/v1/oauth2/revoke
• JWKS: PIPESHUB_INSTANCE_URL/.well-known/jwks.json

Troubleshooting

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

This means the client is trying dynamic registration instead of using your pre-configured credentials. Make sure you passed --client-id and --client-secret (Claude Code) or the auth object (Cursor) correctly.

Authentication fails / redirect error

• Ensure the Redirect URI in your OAuth app matches exactly what the client uses:
  • 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
• Make sure the OAuth app is active (not suspended) in PipesHub

Cannot reach MCP endpoint

• Verify the endpoint is accessible: curl -X POST PIPESHUB_INSTANCE_URL/mcp (should return 401, not connection error)
• Check that your PipesHub instance has MCP enabled

Debugging with MCP Inspector

npx @modelcontextprotocol/inspector

Then connect to PIPESHUB_INSTANCE_URL/mcp with a Bearer token to test the endpoint directly.

FAQ