Skip to main content
Instead of connecting to PipesHub’s remote MCP endpoint, you can run the MCP server locally as a stdio process using the @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
  • Authentication credentials: a Personal Access Token (recommended — no OAuth app setup needed) or OAuth Client ID + Secret
No instance yet? Stand one up with Local Docker demo, then come back here. Do not scaffold LangChain.
For the --bearer-auth flag used throughout this page, a Personal Access Token is the easiest option: create one under Developer Settings > Personal Access Tokens and use it directly — no OAuth app, redirect URIs, or token exchange required.

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

​
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:
For MCP client configuration, replace npx @pipeshub-ai/mcp with node ./bin/mcp-server.js:
To debug with MCP Inspector:

​
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-After header asks, or, without one, about half a second and then a second.
  • A Retry-After longer than 30 seconds isn’t waited out. The tool’s error says how long PipesHub asked to wait instead.
  • Only GET, HEAD, OPTIONS, PUT and DELETE requests are retried. Search and chat are POST requests 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, PUT or DELETE can take up to about three minutes at the defaults (three tries plus the waits between them). Search and chat get one try.
When a call fails because PipesHub can’t be reached, the tool’s error names the address, gives the reason (for example a refused connection or an untrusted certificate), and says to check the --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:
A value that isn’t a whole number in these ranges is refused, with a message saying what it must be.

​
CLI Help

For a full list of server arguments: