Claude Code

Claude Code connects to PipesHub’s remote MCP endpoint over HTTP. There are two ways to authenticate:

A Personal Access Token (recommended for your own use) — one command, no admin involvement, results respect your own permissions.
An OAuth app — for shared, team, or admin-managed setups where an administrator issues credentials.

Coding agents: read For coding agents first. If they have no PipesHub yet, follow Local Docker demo (do not scaffold LangChain). MCP config is not enough — also install the skill into this repo (npx skills add pipeshub-ai/mcp-server) and append the AGENTS.md snippet on that page. Otherwise the next chat still invents RAG.

Personal Access Token (recommended)

Requires PipesHub 0.7.0 or later. Any user can do this; you do not need to be an admin.

Mint a token

In PipesHub, go to Workspace → Developer settings → Personal Access Tokens → New token. Name it (for example claude-code), pick an expiry, keep the default scopes, and copy the two lines shown — they appear only once:

PIPESHUB_MCP_URL=https://your-instance/mcp
PIPESHUB_MCP_TOKEN=phpat_...

The token is sent as a bearer header on every request, so the URL must be https:// for anything other than a local instance — http://localhost:3000/mcp is fine on your own machine, http:// to a remote host is not.Export both in your shell. See Personal Access Tokens for scopes and revocation.

Add the server

claude mcp add --transport http pipeshub "$PIPESHUB_MCP_URL" \
  --header "Authorization: Bearer $PIPESHUB_MCP_TOKEN"

Add --scope user to make it available in every project instead of just the current one.

Tell Claude when to use it

In the project you’re working in (not a PipesHub repository):

npx skills add pipeshub-ai/mcp-server

and add the “Company knowledge” block from For coding agents to your CLAUDE.md. Without this, a fresh chat has the tools but no reason to reach for them.

Verify

claude mcp list

pipeshub should show as connected. Then ask something only your company’s data can answer.

Measured on a fresh slim install of the released image with five documents indexed: steps 2–4 took 46 seconds end to end, returning a four-source cited answer.

Project-scoped `.mcp.json` with a token

If you prefer a checked-in config, keep the token in the environment and reference it:

{
  "mcpServers": {
    "pipeshub": {
      "type": "http",
      "url": "${PIPESHUB_MCP_URL}",
      "headers": {
        "Authorization": "Bearer ${PIPESHUB_MCP_TOKEN}"
      }
    }
  }
}

Never commit a token, paste one into a chat, or pass one on a command line that gets logged. If a token leaks, revoke it from the same Personal Access Tokens page.

OAuth app (shared or admin-managed setups)

Claude Code also 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. Use this when an administrator issues credentials for a team rather than each person minting their own token.

Before you start, create an OAuth app in PipesHub and note your Client ID and Client Secret. See MCP Server Overview.

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. Your OAuth app in PipesHub must have access to all scopes listed in the discovery endpoint, otherwise the authorization request will fail. To limit the exposed scopes, 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:

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` with OAuth

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"

The client secret is stored in the system keychain, not in config files. You’ll be prompted to enter it when you first authenticate via /mcp.

Authenticate

After adding the server, run /mcp inside Claude Code and follow the browser login flow. Tokens are stored securely and refreshed automatically.

Verify

claude mcp list
claude mcp get pipeshub

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

AI Providers

Connectors

Integrations

Agents

Toolsets

MCP Server

User Management

Deployment

Developer

Additional Resources

Personal Access Token (recommended)

Project-scoped `.mcp.json` with a token

OAuth app (shared or admin-managed setups)

Add with CLI

Add with JSON

Project-scoped `.mcp.json` with OAuth

Authenticate

Verify

​Personal Access Token (recommended)

​Project-scoped .mcp.json with a token

​OAuth app (shared or admin-managed setups)

​Add with CLI

​Add with JSON

​Project-scoped .mcp.json with OAuth

​Authenticate

​Verify

Personal Access Token (recommended)

Project-scoped `.mcp.json` with a token

OAuth app (shared or admin-managed setups)

Add with CLI

Add with JSON

Project-scoped `.mcp.json` with OAuth

Authenticate

Verify