Skip to main content
Glama
PipesHub MCP Server

PipesHub MCP Server

Official

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 PipesHub demo on YouTube

▶ 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.

Cursor plugin: a Cursor team admin imports this repository as a team marketplace (Import from Repo; .cursor-plugin/marketplace.json, plugin in cursor-plugin/) to add the local MCP server, the docs search server, the skill, and the ask and setup commands. Sign in once with pipeshub login; no token goes in the config.

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)

Related MCP server: mosadd

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.

  1. 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:

Scope

Used by

semantic:write

pipeshub_search

conversation:chat

pipeshub_chat

agent:read, agent:execute

pipeshub_agents, pipeshub_sources, pipeshub_chat with an agent

kb:read, connector:read, config:read

pipeshub_sources, pipeshub_get_record_content, pipeshub_download_record, pipeshub_indexing_status

kb:write, kb:upload

pipeshub_create_collection, pipeshub_upload

connector:write, connector:sync

pipeshub_add_web_source

user:read, team:read, usergroup:read

pipeshub_directory

code:read

The pipeshub_code_* tools

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:

Placeholder

Description

Example

PIPESHUB_INSTANCE_URL

Your PipesHub instance URL

https://app.pipeshub.com

YOUR_CLIENT_ID

OAuth app client ID

clid_abc123...

YOUR_CLIENT_SECRET

OAuth app client secret

clsec_xyz789...

The remote MCP endpoint URL is: PIPESHUB_INSTANCE_URL/mcp


Remote MCP Setup

Cursor supports static OAuth for remote MCP servers via the auth object in mcp.json.

Configuration

Open Cursor Settings > Tools and Integrations > New MCP Server, or edit your project's .cursor/mcp.json:

{
  "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 will auto-discover the authorization and token endpoints via PipesHub's /.well-known/oauth-protected-resource/mcp metadata.

Note: If the scopes field is omitted, Cursor fetches /.well-known/oauth-protected-resource/mcp and requests all scopes_supported listed there. To limit access, explicitly list only the scopes you need. You can also control which scopes are exposed server-side — see Customizing Default Scopes.

Using Environment Variables

Use Cursor's ${env:VAR} interpolation to keep secrets out of config files:

{
  "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 uses a fixed redirect URI for all MCP servers:

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

Register this as the allowed redirect URI when creating the OAuth app in PipesHub.

OAuth Login Troubleshooting

If Cursor's internal browser fails to load the OAuth login page, copy the authorization URL from the internal browser and paste it into your normal browser to complete the login flow.

Claude Code supports remote HTTP MCP servers with static OAuth credentials via --client-id, --client-secret, and --callback-port.

PipesHub exposes discovery at /.well-known/oauth-protected-resource/mcp, so Claude Code auto-discovers the authorization and token endpoints.

Important: Claude Code does not support configuring specific scopes. It fetches /.well-known/oauth-protected-resource/mcp, reads the scopes_supported list, and requests all of them. PipesHub lists only the scopes the MCP tools use. Give your OAuth app all of them: sign-in grants the ones the app allows, tools that need a missing scope are refused, and sign-in fails with invalid_scope if the app allows none of them. To see or limit the list, see Customizing Default Scopes.

Add with CLI

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

--client-secret without a value prompts for masked input. To skip the prompt, set the MCP_CLIENT_SECRET environment variable:

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

To make it available across all projects:

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

Add with JSON

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

Project-Scoped (.mcp.json)

Create a .mcp.json file in your project root. This can be committed to version control (secrets stay out via env vars):

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

Set environment variables before launching Claude Code:

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

Note: The client secret is stored in the system keychain, not in config files. You'll be prompted to enter it when you first authenticate via /mcp.

Authenticate

After adding the server, run /mcp inside Claude Code and follow the browser login flow. Tokens are stored securely and refreshed automatically.

Verify

claude mcp list
claude mcp get pipeshub

Gemini CLI supports remote MCP servers with OAuth via dynamic_discovery (the default), which auto-discovers authorization and token endpoints from PipesHub's /.well-known/oauth-protected-resource/mcp.

Option A: Settings File

Edit ~/.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"
        ]
      }
    }
  }
}

Note: Adjust the scopes list to match what your OAuth app was granted. If you only need a subset of tools, you can limit the scopes accordingly.

Option B: CLI Command

gemini mcp add --transport http pipeshub PIPESHUB_INSTANCE_URL/mcp

Then edit ~/.gemini/settings.json to add the oauth block as shown above.

Authenticate

Inside Gemini CLI, use the /mcp auth commands:

# 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

On first connection, Gemini will automatically detect the 401 response, discover the OAuth endpoints, and open a browser for login. Tokens are stored securely in ~/.gemini/mcp-oauth-tokens.json and refreshed automatically.

Manage Servers

# 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 Configuration Properties

Property

Required

Description

clientId

Yes

OAuth 2.0 Client ID from PipesHub

clientSecret

No

OAuth 2.0 Client Secret (for confidential clients)

scopes

No

OAuth scopes to request

authorizationUrl

No

Override authorization endpoint (auto-discovered by default)

tokenUrl

No

Override token endpoint (auto-discovered by default)

redirectUri

No

Override redirect URI (defaults to http://localhost:7777/oauth/callback)

Note: OAuth requires a local browser. It will not work in headless environments, remote SSH without X11 forwarding, or containers without browser access.

Codex CLI (OpenAI Codex) connects to remote MCP servers over Streamable HTTP, configured with a [mcp_servers.<name>] table in ~/.codex/config.toml (or .codex/config.toml in your project root to scope it per-project). Codex's HTTP transport authenticates with a bearer token read from an environment variable, so pass a PipesHub JWT bearer token.

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

bearer_token_env_var is the name of the environment variable that holds the token — export it before launching Codex:

export PIPESHUB_BEARER_TOKEN="YOUR_BEARER_TOKEN"

The token is the raw JWT, without the Bearer keyword.

Or add it with the CLI:

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

--bearer-token-env-var takes the name of the environment variable holding the token, not the token value itself.

Verify

# List configured MCP servers
codex mcp list

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

Claude.ai supports custom connectors via remote MCP servers. This lets you use PipesHub tools directly in the Claude.ai web interface without any local setup.

Note: This feature is currently in beta. Free plan users are limited to one custom connector.

Claude.ai Connectors Settings

Claude.ai Add Custom Connector Dialog

For Individual Users (Pro / Max Plans)

  1. Go to claude.ai and navigate to Settings > Connectors

  2. Click Add custom connector at the bottom of the Connectors section

  3. Enter the MCP server URL:

    PIPESHUB_INSTANCE_URL/mcp
  4. Click Advanced settings and enter your OAuth credentials:

    • OAuth Client ID: YOUR_CLIENT_ID

    • OAuth Client Secret: YOUR_CLIENT_SECRET

  5. Click Add

  6. You'll be redirected to PipesHub's login page to authenticate and grant permissions

  7. After authenticating, the connector will be active and PipesHub tools will be available in your Claude.ai conversations

For Team / Enterprise Plans

Organization Owners must first add the connector:

  1. Navigate to Organization settings > Connectors

  2. Click Add custom connector

  3. Enter the MCP server URL: PIPESHUB_INSTANCE_URL/mcp

  4. Click Advanced settings and enter the OAuth Client ID and Client Secret

  5. Click Add

Team members can then connect:

  1. Go to Settings > Connectors

  2. Find the PipesHub connector (marked with a "Custom" label)

  3. Click Connect to authenticate via PipesHub's OAuth login

Redirect URI

Claude.ai uses the following redirect URI for OAuth:

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

Register this as an allowed redirect URI in your PipesHub OAuth app.

Security Notes

  • Only connect to trusted MCP servers

  • Review the permissions requested during the OAuth authentication flow

  • Claude.ai interacts with PipesHub on your behalf using the granted OAuth token — your password is never shared

LibreChat supports remote MCP servers with OAuth authentication via its custom connectors UI. This lets you connect PipesHub tools to any model available in your LibreChat instance.

LibreChat MCP Configuration

Configuration

  1. Log in to your LibreChat instance

  2. Navigate to MCP Servers settings panel

  3. Click Add to create a new custom MCP connector

  4. Fill in the connector details:

    • Name: Pipeshub (or any name you prefer)

    • MCP Server URL: PIPESHUB_INSTANCE_URL/mcp

    • Transport: Select Streamable HTTPS

    • Authentication: Select OAuth

  5. Enter your OAuth credentials:

    • Client ID: YOUR_CLIENT_ID

    • Client Secret: YOUR_CLIENT_SECRET

    • Authorization URL: PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize

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

    • Scope: openid email (or additional scopes as needed)

  6. Check I trust this application

  7. Click Add to save the connector

  8. After adding, LibreChat will generate a Redirect URI displayed in the connector settings panel (next to the copy button). It follows this format:

    http://localhost:3080/api/mcp/<server-identifier>/oauth/callback
  9. Copy the Redirect URI and register it as an allowed redirect URI in your PipesHub OAuth app (see Step 1)

  10. Return to the LibreChat connector and click Update to initiate the OAuth flow — you'll be redirected to PipesHub's login page to authenticate and grant permissions

Redirect URI

LibreChat generates the redirect URI after the connector is created. The URI follows this format:

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

Where <server-identifier> is the unique identifier assigned by LibreChat (visible at the top of the connector settings as "Unique Server Identifier"). You must copy this URI and add it to your PipesHub OAuth app's allowed redirect URIs before authenticating.

Note: If your LibreChat instance runs on a different host or port, the URI will reflect that (e.g., https://chat.example.com/api/mcp/pipeshub/oauth/callback).

Scopes

LibreChat allows you to specify the OAuth scopes in the Scope field. Use a space-separated list:

openid email

To request PipesHub-specific scopes, add them to the scope field:

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

Note: Sign-in grants only the requested scopes your OAuth app in PipesHub allows, so request the scopes the app was granted. See Customizing Default Scopes for details.


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.

    • No account yet: pipeshub init --client <name> creates a trial workspace on instances that offer them (PipesHub Cloud by default; it stays open for 3 days), signs the CLI in to it the same way, and adds PipesHub to that client. Add files with pipeshub collection create and pipeshub upload. It will not replace an existing sign-in without --force. When the instance returns a claim link, init prints it (and pipeshub auth status shows it again): the person who opens it becomes the workspace's admin and keeps it, and the CLI then signs in as them with pipeshub login --url <origin> --no-wait and pipeshub login --wait.

    • 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:

Placeholder

Description

Example

PIPESHUB_INSTANCE_URL

Your PipesHub instance URL

https://app.pipeshub.com

YOUR_BEARER_TOKEN

Your personal access token

phpat_...

Configure in Claude Desktop settings (claude_desktop_config.json):

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

Open Cursor Settings > Tools and Integrations > New MCP Server, or edit your project's .cursor/mcp.json:

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

Run the MCP server as a local stdio process with your personal access token. Edit ~/.codex/config.toml (or .codex/config.toml in your project root):

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

Open Command Palette > MCP: Open User Configuration, then add:

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

Open Windsurf Settings > Cascade > Manage MCPs > View raw config, then add:

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

To run the local MCP server from a cloned repository instead of the npm package:

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

For MCP client configuration, replace npx @pipeshub-ai/mcp with 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"
      ]
    }
  }
}

To debug with MCP Inspector:

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

Local HTTP server

serve (and start --transport sse) listens on 127.0.0.1 only. Pass --host 0.0.0.0 to accept connections from other machines. A browser request is answered only when its Origin is localhost, 127.0.0.1 or [::1]; any other origin gets 403. Clients that send no Origin (CLIs, desktop apps) are unaffected.

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:

Variable

Default

Meaning

PIPESHUB_MCP_MAX_ATTEMPTS

3

Tries per request, the first one included, from 1 to 10. 1 turns retries off.

PIPESHUB_MCP_TIMEOUT_MS

60000

Milliseconds to wait for PipesHub to start answering. 0 turns the timeout off.


Read-only mode

Three tools write, and none of them delete or overwrite. pipeshub_create_collection and pipeshub_upload add collections and documents; they need the kb:write and kb:upload scopes. pipeshub_add_web_source sets up a Web connector that crawls a website now and daily; it also needs connector:write and connector:sync (scope group connect). To serve read tools only from the local server, pass --scope read to start or serve. On the remote /mcp, a token is offered only the write tools its scopes allow.


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

    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

  1. Update the MCP_SCOPES environment variable on your PipesHub instance so it includes the scopes you want clients to get. Discovery lists only the ones the MCP tools use.

  2. Update the OAuth app scopes in PipesHub: go to Settings > Developer Settings > OAuth Apps, select your OAuth app, and add or remove scopes as needed.

  3. Re-authenticate the client — existing tokens carry the old scopes, so you need to re-authenticate to get a new token with the updated scopes. For example:

    • Cursor: Remove and re-add the MCP server, or clear the cached OAuth token and reconnect.

    • Claude Code: Run /mcp and complete the browser login flow again.

    • Gemini CLI: Run /mcp auth pipeshub to re-authenticate.

    • Codex CLI: Update PIPESHUB_BEARER_TOKEN with a fresh token and restart Codex.

    • Claude.ai: Disconnect and reconnect the connector in Settings > Connectors.

Available Tools

7 tools
pipeshub_agentsA
Read-onlyIdempotent

List the PipesHub agents configured for this org, each with its capabilities.

Agents are specialized assistants (custom system prompt, tools, knowledge scope). To converse with one, take its agentId and pass it to pipeshub_chat's agentId argument.

Each agent is returned as: { agentId, name, description, systemPrompt, startMessage, tags, webSearch, isActive, toolsets, knowledge }.

  • toolsets — what the agent can DO: each { name, tools } where name is the connector (e.g. jira, gmail) and tools are the runnable tool ids (e.g. jira.create_issue, gmail.send_email).

  • knowledge — what the agent can READ: each { name, type } (e.g. Confluence-2 / Confluence).

Route on toolsets/knowledge, not the name — names and descriptions are often generic or misleading. Match the request to the agent whose tools can actually perform it (e.g. "create a Jira ticket" → the agent whose toolset is jira and whose tools include jira.create_issue). If NO agent has a tool for the requested action, say so — don't force an unrelated agent.

The list may be empty (no agents configured). For plain Q&A when no specific agent is needed, use pipeshub_chat WITHOUT agentId and pick a chatMode: internal_search (org's indexed knowledge) or web_search (live web). Use agentId everywhere an agent is referenced.

Inputs: search.

pipeshub_chatA

Ask a question, get an answer grounded in the org's indexed data with citations. It reads a few retrieved passages — never a whole document, never a complete list.

Three questions this tool gets WRONG. Check them first:

  • Structure — "what's under this epic?", "which pages are in this space?", "what links to this ticket?", "what's in this folder?" → pipeshub_get_record_content mode:"navigate". Ranking cannot see how records relate.

  • Exhaustive — "how many X?", "list ALL the Y", "every Z" → mode:"navigate", which reports the group's real total. This tool undercounts and will not say so.

  • One named document — summarize it, extract from it, what does it say about X → pipeshub_search for the recordId, then mode:"content".

Everything else about the org's knowledge belongs here: policies, processes, decisions, history, "what do we know about X", and any question spanning several documents.

Internal search (default, chatMode: "internal_search"): the user's documents, files, knowledge base, company policies — anything in their PipesHub-indexed sources (Drive, Box, Confluence, Slack, Gmail, Jira, the org's KB, ...).

Web search (chatMode: "web_search"): current events or public information unlikely to be in the org's knowledge base.

Both are plain-chat modes. Agent chat — pass an agentId from pipeshub_agents — runs against that agent's own prompt, tools and knowledge; quick is its only mode, requires the agentId, and is sent automatically.

  • "What's our policy on Y?" → pipeshub_chat (internal_search)

  • "What's in the news about Z?" → pipeshub_chat (web_search)

  • "Find / locate the file named X" → pipeshub_search (then pipeshub_download_record if the user wants the bytes).

Conversation lifecycle — one tool, both start and continue:

  • First turn: omit conversationId. The server creates a new conversation; capture conversationId from the response.

  • Follow-up turn: pass the conversationId from the previous response. Server-side context is preserved — do NOT replay earlier messages, and filters is ignored on follow-ups (set once at creation).

Only re-omit conversationId (start a fresh conversation) when the user explicitly asks to start over / clear context.

The response contains the AI's answer plus citations. To download a cited document, take citations[*].recordId and call pipeshub_download_record.

Inputs: query (required), agentId, filters, chatMode, +4 more.

pipeshub_directoryA
Read-onlyIdempotent

Look up people, groups, and teams in PipesHub. Five actions — pick action. Not for documents or files: that is pipeshub_search.

  • whoami — the caller's id, email, full name. Use before get_user on yourself. Errors if the credential is expired or revoked.

  • list_users — page org users; search matches name or email.

  • get_user — full User for one userId.

  • list_groups — org groups with userCount; search matches name.

  • list_my_teams — teams the caller is on, with canEdit / canDelete / canManageMembers; search matches name.

Omit page/limit for the first page (page 1). No match is an empty users/groups/teams array, not an error. pagination.hasNextPage (teams: hasNext) says whether to request the next page.

Inputs: action (required), page, limit, search, +1 more.

pipeshub_download_recordA
Read-onlyIdempotent

Download the file as stored for one record — not PipesHub's parsed content, metadata header, or summary.

Use this when the user wants the file itself (download, attach, open). Get recordId from a chat citation or a pipeshub_search hit.

Do not use this to read, summarize, or answer "what does this doc say?" regardless of format. That is pipeshub_get_record_content mode:"content". Text formats come back inline; images, audio, and binary as base64.

convertTo accepts only application/pdf; anything else is ignored.

Inputs: recordId (required), convertTo.

pipeshub_get_record_contentA
Read-onlyIdempotent

Three operations on the org's records. Pick by what you hold:

mode:"lookup" — a URL, issue key (PA-1787), or external ID → its recordId plus the record's metadata mode:"navigate" — a question about structure: what is under X, what links to Y → browses the hierarchy mode:"content" — a recordId, and you need the document's COMPLETE text

mode:"content" (default) — the only way to see a document's complete text. Use it whenever missing part of the document could make the answer wrong: summarize, extract or list ALL of something, check whether or where a doc mentions X, review, or compare named docs. pipeshub_chat cannot do these — it never sees a whole document.

Judge by the user's INTENT, not their keywords: "what's this doc about?", "walk me through the report", "anything in here about Y?" are all full-content tasks. Get the recordId from a pipeshub_search top hit, a chat citation, or mode:"lookup".

Returns one content string: a metadata header (title, source, key fields, pre-generated summary) then the full parsed text. A record with no extractable content returns the literal No record found. Use pipeshub_download_record only for the original file bytes.

mode:"navigate" — browse the hierarchy: RecordGroup (project / space / drive / folder) → Record (epic / story / page / file) → children, with breadcrumbs, related links and record IDs.

Use it when the question depends on structure rather than wording: what is under this epic, which pages sit in this space, what is linked to this ticket, what is in this folder — and every "how many" / "all of" / "every" question. Search ranks by content; only this shows how records relate, and only this gives a count you can trust.

Omit nodeId for a flat listing of everything reachable, most recently updated first — the usual starting point. A URL, an issue key, or a pipeshub_sources id also works and resolves automatically.

Pass depth:2 or depth:3 to see several levels in ONE call — an epic's stories AND their subtasks, a space's pages AND their children — instead of one call per level. Use it whenever the question needs an overview of a hierarchy rather than a single node.

Opening a record also prints that record's own metadata — for a ticket, status, assignee, priority and dates — so a question about one record is often answered by this call alone. It returns no document text; for that, re-call with mode:"content".

Returns Path breadcrumbs, the current node's metadata, a children listing carrying record_id= or node_id= per row plus the group's total (Children 1-50 of 61), Related cross-references, and a Next: line. One page is usually every child, so only pass page:2 when that Next: line says more exist.

mode:"lookup" — turn an external reference into a recordId, the first step whenever the question names one. Returns that record's metadata (for a ticket: status, assignee, priority, dates) plus its recordId, which mode:"navigate" takes to list what is under it and mode:"content" takes to read it.

Handles Jira keys and URLs, Confluence, Drive, Slack permalinks, Linear, Notion, ServiceNow sys_id, SharePoint, Gmail/Outlook, and any connector whose records index a web URL. Resolution searches ALL connectors you can access, regardless of any source filter you used elsewhere.

A miss is a 200 with empty matches and the input echoed in not_found_identifiers — that may mean no-access, not non-existence. Use mode:"navigate" to confirm the record exists before telling the user it does not. If ambiguous is true, pick from matches rather than taking the first.

Navigate and lookup return a rendered text view whose closing Next: line names the exact follow-up call — follow it. When presenting a record, link it using the Web URL from its metadata header (when present).

Inputs: mode, page, depth, limit, +9 more.

pipeshub_sourcesA
Read-onlyIdempotent

Discover available chat sources and AI models in one call.

Returns up to three sections:

  • sources — connectors (kind: "connector") and collections (kind: "knowledgeBase"). For pipeshub_search and pipeshub_chat, put a connector id in apps and a collection id in kb. sourcesTruncated: true means the list stopped at 1,000 sources.

  • llmModels — chat / generation models. Each item's modelKey is the value to pass on pipeshub_chat as modelKey. Pick isDefault: true unless the user asks for a specific model.

  • embeddingModels — vector embedding models (only fetched when explicitly requested via include).

Call this once at the start of a session and cache the result — sources and models change infrequently.

Inputs: include.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: search locates records, chat answers grounded questions, get_record_content reads full text/navigates/looks up, download_record fetches original bytes, and agents/directory/sources handle their own domains. The descriptions explicitly cross-reference and warn against misuse, so an agent can reliably select the right tool.

    Naming Consistency3/5

    All tools share the pipeshub_ prefix, but the pattern after it is inconsistent: some are verb_noun (download_record, get_record_content), some are bare verbs (search, chat), and some are bare nouns (agents, directory, sources). This makes names individually readable but not predictably derivable.

    Tool Count5/5

    Seven tools is a well-scoped size for a knowledge retrieval and chat server. Each tool covers a major capability without unnecessary fragmentation, and no tool feels redundant.

    Completeness5/5

    The surface covers the full read-side workflow: discover sources, search, chat with citations, resolve external references, read full content, navigate hierarchy, download files, and look up agents and people. There are no obvious gaps or dead ends for the server's apparent purpose.

    Maintenance

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers