Claude Desktop

Claude Desktop can talk to the PipesHub MCP server, but there’s one important catch to understand before you start.

Claude Desktop does not support local HTTP MCP transport. Unlike a server-side tool, it won’t connect to a plain http://localhost:.../mcp endpoint. To connect PipesHub you have two options, and which one you pick depends on how PipesHub is hosted:

Add it as a custom connector — works only when PipesHub is reachable over public HTTPS (a real domain with a valid SSL certificate), exactly like Claude.ai (Web).
Run a local stdio bridge — works for localhost / self-hosted instances with no public domain, using the @pipeshub-ai/mcp npm package.

Coding agents standing up a laptop demo: follow Local Docker demo, then use the stdio bridge below. Do not point Claude Desktop’s custom connector at localhost.

Which option should I use?

Your situation	Use this
PipesHub is hosted on a public domain with valid SSL (e.g. `https://app.pipeshub.com`)	Custom connector
PipesHub runs locally or on an internal host without a public HTTPS domain (e.g. `http://localhost:3000`)	Local stdio bridge

Option 1: Custom connector (hosted PipesHub)

If your PipesHub instance is served over HTTPS on a valid domain, Claude Desktop can connect to the remote MCP endpoint directly — no local setup, no npm packages. This is the same flow as Claude.ai (Web).

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

Open Connectors settings

In Claude Desktop, go to Settings > Connectors.

Add a custom connector

Click Add custom connector at the bottom of the Connectors section.

Enter the MCP server URL

Use your public HTTPS instance URL with the /mcp path:

PIPESHUB_INSTANCE_URL/mcp

For example: https://app.pipeshub.com/mcp.

Enter OAuth credentials

Click Advanced settings and enter your OAuth credentials:

OAuth Client ID: YOUR_CLIENT_ID
OAuth Client Secret: YOUR_CLIENT_SECRET

Claude Desktop add custom connector dialog — Add custom connector dialog with Advanced settings

Add and authenticate

Click Add. Claude Desktop opens your browser to PipesHub’s login page so you can authenticate and grant permissions. Once that’s done, the connector goes active and PipesHub becomes visible in your list of connectors.

PipesHub connector active in Claude Desktop

Redirect URI

Claude Desktop uses the same OAuth callback as the Claude web app:

https://claude.ai/api/mcp/auth_callback

A custom connector needs PipesHub to be reachable from the public internet over HTTPS. If you only have a localhost instance, the connector flow won’t work — use Option 2 instead.

Option 2: Local stdio bridge

When PipesHub runs on localhost or an internal host without a public HTTPS domain, run the MCP server locally as a stdio process. Claude Desktop launches the @pipeshub-ai/mcp bridge, which then talks to your PipesHub instance over HTTP on your behalf.

Prerequisites

Node.js 20+ installed
Your PipesHub instance URL (e.g. http://localhost:3000/api/v1)
An OAuth app configured for the Client Credentials grant (see below)

For this route, your OAuth app must have the Client Credentials grant enabled. When you create the OAuth app, choose Client Credentials as the grant type so the bridge can exchange your Client ID and Secret for a token directly — no browser redirect is involved. (The redirect URI used by the connector flow does not apply here.)

Configuration

Open Claude Desktop’s config file (claude_desktop_config.json) and add the PipesHub server. You can find it via Settings > Developer > Edit Config, or at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Replace http://localhost:3000 with your actual instance host, and YOUR_CLIENT_ID / YOUR_CLIENT_SECRET with the credentials from your OAuth app.

Apply the changes

Save the file and fully quit and reopen Claude Desktop (a window reload isn’t enough). Once it restarts, the PipesHub tools appear under the tools menu in your conversations.

PipesHub MCP server showing under Local MCP servers

Troubleshooting

The custom connector won't connect / shows an error

Custom connectors require a public HTTPS endpoint with a valid SSL certificate. Claude Desktop can’t reach http://localhost, self-signed certificates, or private hostnames through the connector flow. Either put PipesHub behind a real domain with valid SSL, or switch to the local stdio bridge.

The stdio server doesn't start

Make sure Node.js 20+ is installed and npx is on your PATH.
Confirm your instance is reachable: curl http://localhost:3000/api/v1 should respond (not a connection refused error).
After editing claude_desktop_config.json, fully quit and relaunch Claude Desktop.

Authentication fails on the stdio bridge

Verify the OAuth app has the Client Credentials grant enabled, and that the --token-url points to your instance’s token endpoint (PIPESHUB_INSTANCE_URL/api/v1/oauth2/token). Double-check the Client ID and Secret are correct and the app is active.

Welcome To PipesHub

System Overview

Authentication

Mail Configuration

AI Providers

Connectors

Integrations

Agents

Toolsets

MCP Server

User Management

Deployment

Developer

Additional Resources

Which option should I use?

Option 1: Custom connector (hosted PipesHub)

Redirect URI

Option 2: Local stdio bridge

Prerequisites

Configuration

Apply the changes

Troubleshooting

​Which option should I use?

​Option 1: Custom connector (hosted PipesHub)

​Redirect URI

​Option 2: Local stdio bridge

​Prerequisites

​Configuration

​Apply the changes

​Troubleshooting

Which option should I use?

Option 1: Custom connector (hosted PipesHub)

Redirect URI

Option 2: Local stdio bridge

Prerequisites

Configuration

Apply the changes

Troubleshooting