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.
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
- A running PipesHub instance: PipesHub Cloud or self-hosted. If they have none yet, start on PipesHub Cloud, or self-host with the Local Docker demo; do not scaffold LangChain.
- Either an OAuth app (see Step 1 below), or a Personal Access Token — see the note below for which one to use
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.
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:Customizing Default Scopes
TheMCP_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:
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):
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:- 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, andpipeshub_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
Incompatible auth server: does not support dynamic client registration
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
Authentication fails / redirect error
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) orhttp://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
Cannot reach MCP endpoint
Cannot reach MCP endpoint
- Verify the endpoint is accessible:
curl -X POST PIPESHUB_INSTANCE_URL/mcp(should return 401, not a connection error).
Request is too large (HTTP 413)
Request is too large (HTTP 413)
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.
Debugging with MCP Inspector
Debugging with MCP Inspector
PIPESHUB_INSTANCE_URL/mcp with a Bearer token to test the endpoint directly.FAQ
How do I update the scopes for my MCP integration?
How do I update the scopes for my MCP integration?
- Update the
MCP_SCOPESenvironment variable on your PipesHub instance and restart. Discovery lists only the scopes the MCP tools use (see Customizing Default Scopes). - 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.
- 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
/mcpand complete the browser login flow again. - Gemini CLI: Run
/mcp auth pipeshubto re-authenticate. - Claude.ai: Disconnect and reconnect the connector in Settings > Connectors.