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. This lets AI clients such as Cursor, Claude Code, Gemini CLI, Claude.ai (Web), and LibreChat search and chat over your organization’s indexed documents, look up people and groups, and download files.
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 (self-hosted or cloud)
  • Either an OAuth app (see Step 1 below), or a Personal Access Token — see the note below for which one to use
The client setup guides below (Cursor, Claude Code, Gemini CLI, Claude.ai, LibreChat) connect over OAuth — you’ll need an OAuth app for those.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 Developer Settings

Log in to your PipesHub instance as an admin and navigate to Settings > Developer Settings > OAuth Apps.
2

Create the app

Click Create OAuth App and fill in the app details:
  • Name: e.g., MCP Integration
  • Redirect URIs: Add the redirect URIs for the clients you plan to use (see the table below).
3

Save and copy credentials

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

​
Redirect URIs

Add all the redirect URIs for the clients you plan to use:
The scopes in MCP_SCOPES must match the scopes granted to your OAuth app — a mismatch will result in an authorization error.

​
Customizing Default Scopes

By default, PipesHub exposes some default scopes in its /.well-known/oauth-protected-resource/mcp discovery endpoint. You can customize which scopes are exposed by setting the MCP_SCOPES environment variable on your PipesHub instance. This is useful for clients like Claude Code that automatically request all exposed scopes. The recommended MCP_SCOPES value covers the common chat, search, and directory workflows:

​
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 static OAuth credentials.

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.

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

​
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: 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
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).
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 to include the new scopes you want exposed via the discovery endpoint.
  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:
    • 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.