Skip to main content
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, start on PipesHub Cloud, or self-host with the 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.
Requires PipesHub 0.7.0 or later. Any user can do this; you do not need to be an admin.
1

Mint a token

In PipesHub, open Workspace settings, select Personal access tokens under Developer settings, and click 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:
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. To use the plugin instead of adding the server by hand, skip to Plugin.
2

Add the server

Keep the single quotes: Claude Code stores the header as written and reads PIPESHUB_MCP_TOKEN from its environment each time it connects, so the token never lands in its config. With double quotes the shell pastes the token itself into the config. Start Claude Code from a shell where the variable is exported.Add --scope user to make it available in every project instead of just the current one.
3

Tell Claude when to use it

In the project you’re working in (not a PipesHub repository):
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.
4

Verify

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

Plugin

Mint a token first (step 1 above). The plugin installs the MCP server, the PipesHub skill, and two commands: /pipeshub:ask <question> and /pipeshub:setup. Run these in your terminal, not inside a Claude Code session:
Newer Claude Code versions also accept the one-step form claude plugin install pipeshub --marketplace pipeshub-ai/mcp-server. It reads two environment variables. Set them in your shell profile, not in a chat, then restart Claude Code:
Without PIPESHUB_MCP_URL the plugin connects to PipesHub Cloud (https://app.pipeshub.com/mcp). Run /pipeshub:setup to check the connection.

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. That list is the part of your instance’s MCP_SCOPES that the MCP tools use, not the whole of MCP_SCOPES. Your OAuth app in PipesHub must have access to every scope in it, otherwise the authorization request will fail. To see or limit the list, see Customizing Default Scopes.

Add with CLI

--client-secret without a value prompts for masked input. To skip the prompt, set the MCP_CLIENT_SECRET environment variable:
To make it available across all projects:

Add with JSON

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):
Set environment variables before launching Claude Code:
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