PipesHub

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 2½-minute demo](https://youtu.be/VgyND38QZ7w): 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:// /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)

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:

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:

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:

The remote MCP endpoint URL is: PIPESHUB_INSTANCE_URL/mcp

Remote MCP Setup

Cursor

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

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:

`bash

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: