Local Server (Stdio)

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

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:

Placeholder	Description	Example
`PIPESHUB_INSTANCE_URL`	Your PipesHub instance URL	`https://app.pipeshub.com`
`YOUR_BEARER_TOKEN`	Personal access token (or any other Bearer JWT)	`phpat_eyJhbGci...`
`YOUR_CLIENT_ID`	OAuth app client ID	`clid_abc123...`
`YOUR_CLIENT_SECRET`	OAuth app client secret	`clsec_xyz789...`

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:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "-y",
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "-y",
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--client-id",
        "YOUR_CLIENT_ID",
        "--client-secret",
        "YOUR_CLIENT_SECRET",
        "--token-url",
        "/api/v1/oauth2/token"
      ]
    }
  }
}

Claude Code CLI

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

claude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

Gemini CLI

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --bearer-auth YOUR_BEARER_TOKEN

gemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \
  --server-url PIPESHUB_INSTANCE_URL \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET \
  --token-url /api/v1/oauth2/token

VS Code

Open Command Palette > MCP: Open User Configuration, then add:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "-y",
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Windsurf

Open Windsurf Settings > Cascade > Manage MCPs > View raw config, then add:

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "-y",
        "@pipeshub-ai/mcp",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

Running from Source (Development)

To run the local MCP server from a cloned repository instead of the npm package:

git clone https://github.com/pipeshub-ai/pipeshub-ai.git
cd pipeshub-ai
npm install
npm run build
node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

For MCP client configuration, replace npx @pipeshub-ai/mcp with node ./bin/mcp-server.js:

{
  "mcpServers": {
    "pipeshub": {
      "command": "node",
      "args": [
        "./bin/mcp-server.js",
        "start",
        "--server-url",
        "PIPESHUB_INSTANCE_URL",
        "--bearer-auth",
        "YOUR_BEARER_TOKEN"
      ]
    }
  }
}

To debug with MCP Inspector:

npx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN

CLI Help

For a full list of server arguments:

npx @pipeshub-ai/mcp --help

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

AI Providers

Connectors

Integrations

Agents

Toolsets

MCP Server

User Management

Deployment

Developer

Additional Resources

Prerequisites

Placeholders

Claude Desktop

Cursor

Claude Code CLI

Gemini CLI

VS Code

Windsurf

Running from Source (Development)

CLI Help

​Prerequisites

​Placeholders

​Claude Desktop

​Cursor

​Claude Code CLI

​Gemini CLI

​VS Code

​Windsurf

​Running from Source (Development)

​CLI Help

Prerequisites

Placeholders

Claude Desktop

Cursor

Claude Code CLI

Gemini CLI

VS Code

Windsurf

Running from Source (Development)

CLI Help