Skip to main content

What is the PipesHub MCP Server?

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.
If you are a coding agent (or setting one up), start at For coding agents.
This lets AI clients such as Cursor, Claude Code, Gemini CLI, Claude.ai (Web), LibreChat, and Omnigent search and chat over your organization’s indexed documents, look up people and groups, and download files. Here’s Claude Code using PipesHub over MCP, with each person’s own permissions:
Looking for the tool reference? See Tools Reference for descriptions, arguments, and a decision guide for each tool the MCP server exposes.
QM is not an MCP client. It cannot attach to /mcp the way the clients below can. The integration is a pipeshub CLI inside the agent sandbox — see Use with QM.

Prerequisites

Most client setup guides below (Cursor, Gemini CLI, Claude.ai, LibreChat) connect over OAuth — you’ll need an OAuth app for those. Claude Code and Omnigent are the exceptions: they attach with an Authorization header, so a personal access token is all you need. Claude Code can also use an OAuth app for shared or admin-managed setups.For your own tooling, skip OAuth entirely: create a Personal Access Token under Developer settings > Personal access tokens and use it as a Bearer token, either directly against /mcp, as --bearer-auth with the Local Server (Stdio) package, or with any MCP client you configure yourself with a custom Authorization header.

Step 1: Create an OAuth App

1

Open OAuth 2.0 apps

Sign in to PipesHub, open Workspace settings, and select OAuth 2.0 apps under Developer settings. Any member can create an app; an admin is offered more scopes to grant it.
2

Create the app

Click New OAuth application. On the General tab, fill in:
  • App name: e.g., MCP Integration
  • Redirect URI: add the redirect URI of each client you plan to use (see the table below), up to 10.
Click Next. On Permissions & scopes, select every scope the discovery endpoint lists, then click Create app.
3

Copy the credentials

Copy the Client ID and Client secret. The secret is not shown again.

Redirect URIs

Add all the redirect URIs for the clients you plan to use:
Your OAuth app must be granted every scope the discovery endpoint lists (see Customizing Default Scopes). Clients such as Claude Code request all of them, and a scope the app lacks causes an authorization error.

Customizing Default Scopes

The MCP_SCOPES environment variable is the most any personal access token or OAuth token on your instance may hold. The discovery endpoint, /.well-known/oauth-protected-resource/mcp, does not list all of it: its scopes_supported holds only the MCP_SCOPES entries that the MCP tools use. Clients such as Claude Code request every scope in that list, so check it before you grant scopes to an OAuth app:
The scopes the MCP tools use are offline_access, semantic:write, conversation:chat, agent:read, agent:execute, kb:read, kb:write, kb:upload, connector:read, config:read, connector:write, connector:sync, user:read, team:read, usergroup:read and code:read. A scope you remove from MCP_SCOPES also drops out of discovery. This is the MCP_SCOPES value PipesHub ships (backend/env.template). It covers chat, search, the directory, agents and code. It also lets an agent create collections and upload into them (kb:write, kb:upload), and add a website as a source (connector:write, connector:sync):
Leave kb:write and kb:upload out to stop agents creating collections and uploading, and connector:write and connector:sync out to stop them adding web sources: tokens without them are not offered those tools. With the connector scopes, a token can also create and configure the user’s other connectors and start or stop their syncs, as the user could in the connectors page. Other tools that can act, such as pipeshub_chat with an agent whose toolsets take actions, are governed by their own scopes. An instance that sets MCP_SCOPES in its .env keeps that list after an upgrade until you edit it. After you add the two scopes and restart, new personal access tokens get them, and the built-in PipesHub agent app (device login) adds them to its allowed scopes on the next discovery request. Tokens already issued keep their scopes: mint a new token, or sign the agent in again. An MCP client that registered itself (Dynamic Client Registration) keeps the scopes it registered with, so remove and re-add the server in that client to give it new ones.

Placeholders

Replace these placeholders in all client configurations: The remote MCP endpoint URL is: PIPESHUB_INSTANCE_URL/mcp

Client Setup Guides

Pick your client to connect it to the PipesHub MCP server:

Cursor

Remote MCP via the auth object in mcp.json.

Claude Code

Remote HTTP MCP with a personal access token, or an OAuth app for shared setups.

Gemini CLI

Remote MCP with OAuth dynamic discovery.

Claude.ai (Web)

Custom connectors in the Claude.ai web interface.

Claude Desktop

Custom connector (hosted) or a local stdio bridge.

LibreChat

Remote MCP via the custom connectors UI.

Omnigent

Open-source agent framework — attach with a personal access token.

Local Server (Stdio)

Run the MCP server locally as a stdio process.

QM

CLI in the agent sandbox — not an MCP attachment.

How It Works

Architecture

OAuth Protected Resource Discovery

PipesHub exposes OAuth protected resource discovery at:
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

Request size limit

PipesHub accepts MCP requests of up to 5 MB. A larger request is refused with HTTP 413 and a JSON-RPC error that gives the limit. Real tool calls are far smaller. A chat question can be at most 100,000 characters, and pipeshub_upload sends at most about 3 MB per call; use pipeshub upload from the CLI for larger files. If a client hits the limit, send less in one call, such as a shorter question or fewer IDs.

Troubleshooting

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.
Ensure the Redirect URI in your OAuth app matches exactly what the client uses:
  • Cursor: https://www.cursor.com/agents/mcp/oauth/callback (web and Cursor Agents) or http://localhost:8787/callback (desktop app)
  • 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
Also make sure the OAuth app is active (not suspended) in PipesHub.
  • Verify the endpoint is accessible: curl -X POST PIPESHUB_INSTANCE_URL/mcp (should return 401, not a connection error).
One MCP request can be at most 5 MB. Send less in one call, such as a shorter question or fewer IDs, and try again.
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 and restart. Discovery lists only the scopes the MCP tools use (see Customizing Default Scopes).
  2. Update the OAuth app scopes in PipesHub: open Workspace settings > Developer settings > OAuth 2.0 apps, click Manage on your app, and add or remove scopes.
  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:
    • 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.
    • Claude.ai: Disconnect and reconnect the connector in Settings > Connectors.