@pipeshub-ai/mcp npm package. This is useful when you prefer a local setup or need to work in environments where direct HTTP connections to the remote MCP endpoint aren’t practical.
Prerequisites
- Node.js 20+ installed
- A PipesHub instance URL
- A credential that acts as you, so results follow your permissions: a
pipeshub loginsign-in (no token in any config, below) or a Personal Access Token
No token in the config
With@pipeshub-ai/mcp 4.7.0 or later, sign the CLI in once and let it write the client entry:
npx -y @pipeshub-ai/mcp@>=4.7.0 start --server-url <origin> with no --bearer-auth: the local server uses the pipeshub login sign-in and refreshes it, so no token is written into the client’s config. An agent setting this up runs pipeshub login --no-wait, gives the user the link and code, then pipeshub login --wait. --dry-run shows what mcp install would change, and --force replaces an existing pipeshub entry.
The sign-in keeps refreshing on PipesHub versions that give device logins a refresh token; on older ones it lasts an hour. With no --bearer-auth and no sign-in, start also accepts PIPESHUB_TOKEN from the environment, sent only to --server-url or PIPESHUB_BASE_URL.
The “Signed in” tabs below are the same entries written by hand.
Placeholders
Replace these in all configurations below:Claude Desktop
Claude Desktop has its own dedicated guide, since it can’t connect to a local HTTP MCP endpoint and needs either a custom connector (hosted) or this stdio bridge. See Claude Desktop for the full setup.Cursor
Open Cursor Settings > Tools and Integrations > New MCP Server, or edit your project’s.cursor/mcp.json:
Claude Code CLI
Gemini CLI
VS Code
Open Command Palette >MCP: Open User Configuration, then add. VS Code uses the top-level key servers, not mcpServers:
Windsurf
Open Windsurf Settings > Cascade > Manage MCPs > View raw config, then add:Running from Source (Development)
To run the local MCP server from a cloned repository instead of the npm package:npx @pipeshub-ai/mcp with node ./bin/mcp-server.js:
Retries and timeouts
The local server (start and serve) waits out short outages on requests that are safe to repeat:
- A request refused with 429, 502, 503 or 504 is retried, three tries in all. The server waits as long as PipesHub’s
Retry-Afterheader asks, or, without one, about half a second and then a second. - A
Retry-Afterlonger than 30 seconds isn’t waited out. The tool’s error says how long PipesHub asked to wait instead. - Only
GET,HEAD,OPTIONS,PUTandDELETErequests are retried. Search and chat arePOSTrequests and are never retried, because a repeat would be a second search or a second answer. - Each try that gets no response within 60 seconds is abandoned. The limit covers the wait for PipesHub to start answering, so a long chat answer that is already streaming is not cut off. The limit applies to each try, not to the whole call. A try that gets no answer at all ends the call without a retry, but when slow tries end in a 429, 502, 503 or 504 and are retried, a
GET,PUTorDELETEcan take up to about three minutes at the defaults (three tries plus the waits between them). Search and chat get one try.
--server-url or --instance-url the server was started with. When a call times out, the error says to try again, check that PipesHub is healthy, or raise PIPESHUB_MCP_TIMEOUT_MS. The request’s bearer token (if it is at least eight characters) is removed from the body of any 4xx or 5xx response before the model sees it. Error text inside a successful streamed answer is passed on as it is.
Change the defaults with environment variables, in your MCP client’s env block or with --env NAME=VALUE: