Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.pipeshub.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Prerequisites

  • A running PipesHub instance (self-hosted or cloud)
  • An OAuth app created in PipesHub (see Step 1 below)

​
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:
ClientRedirect URI
Cursorcursor://anysphere.cursor-mcp/oauth/callback
Claude Codehttp://localhost:<PORT>/callback (e.g., http://localhost:8080/callback)
Claude.ai (Web)https://claude.ai/api/mcp/auth_callback
Gemini CLIhttp://localhost:7777/oauth/callback
LibreChathttp://localhost:3080/api/mcp/<server-identifier>/oauth/callback
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: 
MCP_SCOPES=openid,profile,email,offline_access,semantic:write,conversation:write,conversation:chat,kb:read,team:read,user:read,config:read

​
Placeholders

Replace these placeholders in all client configurations:
PlaceholderDescriptionExample
PIPESHUB_INSTANCE_URLYour PipesHub instance URLhttps://app.pipeshub.com
YOUR_CLIENT_IDOAuth app client IDclid_abc123...
YOUR_CLIENT_SECRETOAuth app client secretclsec_xyz789...
YOUR_BEARER_TOKENJWT Bearer token (local stdio only)eyJhbGci...
The remote MCP endpoint URL is: PIPESHUB_INSTANCE_URL/mcp

​
Client Setup Guides

Pick your client to connect it to the PipesHub MCP server:
https://mintcdn.com/pipeshub/I90RgXEJC2oIYd5s/logo/cursor.svg?fit=max&auto=format&n=I90RgXEJC2oIYd5s&q=85&s=7666c0bf7dfdc161b9a9f86462ad854d

Cursor

Remote MCP via the auth object in mcp.json.
https://mintcdn.com/pipeshub/I90RgXEJC2oIYd5s/logo/claude.svg?fit=max&auto=format&n=I90RgXEJC2oIYd5s&q=85&s=41ff7df262def9c8efb99c98d0e0431d

Claude Code

Remote HTTP MCP with static OAuth credentials.
https://mintcdn.com/pipeshub/I90RgXEJC2oIYd5s/logo/gemini.svg?fit=max&auto=format&n=I90RgXEJC2oIYd5s&q=85&s=e40a87d48dbbcfe535d536316af822f8

Gemini CLI

Remote MCP with OAuth dynamic discovery.
https://mintcdn.com/pipeshub/I90RgXEJC2oIYd5s/logo/claude.svg?fit=max&auto=format&n=I90RgXEJC2oIYd5s&q=85&s=41ff7df262def9c8efb99c98d0e0431d

Claude.ai (Web)

Custom connectors in the Claude.ai web interface.
https://mintcdn.com/pipeshub/I90RgXEJC2oIYd5s/logo/librechat.svg?fit=max&auto=format&n=I90RgXEJC2oIYd5s&q=85&s=089a0b2c90c58a8fa1e85eef404395c4

LibreChat

Remote MCP via the custom connectors UI.

Local Server (Stdio)

Run the MCP server locally as a stdio process.

​
How It Works

​
Architecture

AI Client (Cursor / Claude Code / Gemini 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 Reference)

​
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

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