Cursor

\n\nCursor supports static OAuth for remote MCP servers via the `auth` object in `mcp.json`.\n\n### Configuration\n\nOpen Cursor Settings > Tools and Integrations > New MCP Server, or edit your project's `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"url\": \"PIPESHUB_INSTANCE_URL/mcp\",\n \"auth\": {\n \"CLIENT_ID\": \"YOUR_CLIENT_ID\",\n \"CLIENT_SECRET\": \"YOUR_CLIENT_SECRET\",\n \"scopes\": [\n \"org:read\", \"org:write\", \"org:admin\",\n \"user:read\", \"user:write\", \"user:invite\", \"user:delete\",\n \"usergroup:read\", \"usergroup:write\",\n \"team:read\", \"team:write\",\n \"kb:read\", \"kb:write\", \"kb:delete\", \"kb:upload\",\n \"semantic:read\", \"semantic:write\", \"semantic:delete\",\n \"conversation:read\", \"conversation:write\", \"conversation:chat\",\n \"agent:read\", \"agent:write\", \"agent:execute\",\n \"connector:read\", \"connector:write\", \"connector:sync\", \"connector:delete\",\n \"config:read\", \"config:write\",\n \"document:read\", \"document:write\", \"document:delete\",\n \"crawl:read\", \"crawl:write\", \"crawl:delete\"\n ]\n }\n }\n }\n}\n```\n\nCursor will auto-discover the authorization and token endpoints via PipesHub's `/.well-known/oauth-protected-resource/mcp` metadata.\n\n> **Note:** If the `scopes` field is omitted, Cursor fetches `/.well-known/oauth-protected-resource/mcp` and requests **all** `scopes_supported` listed there. To limit access, explicitly list only the scopes you need. You can also control which scopes are exposed server-side — see [Customizing Default Scopes](#customizing-default-scopes).\n\n### Using Environment Variables\n\nUse Cursor's `${env:VAR}` interpolation to keep secrets out of config files:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"url\": \"${env:PIPESHUB_INSTANCE_URL}/mcp\",\n \"auth\": {\n \"CLIENT_ID\": \"${env:PIPESHUB_CLIENT_ID}\",\n \"CLIENT_SECRET\": \"${env:PIPESHUB_CLIENT_SECRET}\",\n \"scopes\": [\n \"kb:read\", \"kb:write\",\n \"semantic:read\", \"semantic:write\",\n \"conversation:read\", \"conversation:write\", \"conversation:chat\",\n \"agent:read\", \"agent:write\", \"agent:execute\",\n \"connector:read\", \"connector:write\",\n \"config:read\", \"user:read\"\n ]\n }\n }\n }\n}\n```\n\n### Redirect URI\n\nCursor uses a fixed redirect URI for all MCP servers:\n\n```\ncursor://anysphere.cursor-mcp/oauth/callback\n```\n\nRegister this as the allowed redirect URI when creating the OAuth app in PipesHub.\n\n### OAuth Login Troubleshooting\n\nIf Cursor's internal browser fails to load the OAuth login page, copy the authorization URL from the internal browser and paste it into your normal browser to complete the login flow.\n\n

\n\n

Claude Code

\n\nClaude Code supports remote HTTP MCP servers with static OAuth credentials via `--client-id`, `--client-secret`, and `--callback-port`.\n\nPipesHub exposes discovery at `/.well-known/oauth-protected-resource/mcp`, so Claude Code auto-discovers the authorization and token endpoints.\n\n> **Important:** 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. Your OAuth app in PipesHub **must have access to all scopes** listed in the discovery endpoint, otherwise the authorization request will fail. To limit the exposed scopes, see [Customizing Default Scopes](#customizing-default-scopes).\n\n### Add with CLI\n\n```bash\nclaude mcp add --transport http \\\n --client-id YOUR_CLIENT_ID \\\n --client-secret \\\n --callback-port 8080 \\\n pipeshub PIPESHUB_INSTANCE_URL/mcp\n```\n\n> `--client-secret` without a value prompts for masked input. To skip the prompt, set the `MCP_CLIENT_SECRET` environment variable:\n>\n> ```bash\n> MCP_CLIENT_SECRET=YOUR_CLIENT_SECRET claude mcp add --transport http \\\n> --client-id YOUR_CLIENT_ID \\\n> --client-secret \\\n> --callback-port 8080 \\\n> pipeshub PIPESHUB_INSTANCE_URL/mcp\n> ```\n\nTo make it available across all projects:\n\n```bash\nclaude mcp add --transport http --scope user \\\n --client-id YOUR_CLIENT_ID \\\n --client-secret \\\n --callback-port 8080 \\\n pipeshub PIPESHUB_INSTANCE_URL/mcp\n```\n\n### Add with JSON\n\n```bash\nclaude mcp add-json pipeshub '{\n \"type\": \"http\",\n \"url\": \"PIPESHUB_INSTANCE_URL/mcp\",\n \"oauth\": {\n \"clientId\": \"YOUR_CLIENT_ID\",\n \"callbackPort\": 8080\n }\n}' --client-secret\n```\n\n### Project-Scoped (`.mcp.json`)\n\nCreate a `.mcp.json` file in your project root. This can be committed to version control (secrets stay out via env vars):\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"type\": \"http\",\n \"url\": \"${PIPESHUB_INSTANCE_URL}/mcp\",\n \"oauth\": {\n \"clientId\": \"${PIPESHUB_CLIENT_ID}\",\n \"callbackPort\": 8080\n }\n }\n }\n}\n```\n\nSet environment variables before launching Claude Code:\n\n```bash\nexport PIPESHUB_INSTANCE_URL=\"https://app.pipeshub.com\"\nexport PIPESHUB_CLIENT_ID=\"your-client-id\"\n```\n\n> **Note:** 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`.\n\n### Authenticate\n\nAfter adding the server, run `/mcp` inside Claude Code and follow the browser login flow. Tokens are stored securely and refreshed automatically.\n\n### Verify\n\n```bash\nclaude mcp list\nclaude mcp get pipeshub\n```\n\n

\n\n

Gemini CLI

\n\nGemini CLI supports remote MCP servers with OAuth via `dynamic_discovery` (the default), which auto-discovers authorization and token endpoints from PipesHub's `/.well-known/oauth-protected-resource/mcp`.\n\n### Option A: Settings File\n\nEdit `~/.gemini/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"url\": \"PIPESHUB_INSTANCE_URL/mcp\",\n \"oauth\": {\n \"clientId\": \"YOUR_CLIENT_ID\",\n \"clientSecret\": \"YOUR_CLIENT_SECRET\",\n \"scopes\": [\n \"org:read\", \"org:write\", \"org:admin\",\n \"user:read\", \"user:write\", \"user:invite\", \"user:delete\",\n \"usergroup:read\", \"usergroup:write\",\n \"team:read\", \"team:write\",\n \"kb:read\", \"kb:write\", \"kb:delete\", \"kb:upload\",\n \"semantic:read\", \"semantic:write\", \"semantic:delete\",\n \"conversation:read\", \"conversation:write\", \"conversation:chat\",\n \"agent:read\", \"agent:write\", \"agent:execute\",\n \"connector:read\", \"connector:write\", \"connector:sync\", \"connector:delete\",\n \"config:read\", \"config:write\",\n \"document:read\", \"document:write\", \"document:delete\",\n \"crawl:read\", \"crawl:write\", \"crawl:delete\"\n ]\n }\n }\n }\n}\n```\n\n> **Note:** Adjust the `scopes` list to match what your OAuth app was granted. If you only need a subset of tools, you can limit the scopes accordingly.\n\n### Option B: CLI Command\n\n```bash\ngemini mcp add --transport http pipeshub PIPESHUB_INSTANCE_URL/mcp\n```\n\nThen edit `~/.gemini/settings.json` to add the `oauth` block as shown above.\n\n### Authenticate\n\nInside Gemini CLI, use the `/mcp auth` commands:\n\n```bash\n# List servers and their auth status\n/mcp auth\n\n# Authenticate with PipesHub (opens browser for login)\n/mcp auth pipeshub\n\n# Re-authenticate if tokens expire\n/mcp auth pipeshub\n```\n\nOn first connection, Gemini will automatically detect the 401 response, discover the OAuth endpoints, and open a browser for login. Tokens are stored securely in `~/.gemini/mcp-oauth-tokens.json` and refreshed automatically.\n\n### Manage Servers\n\n```bash\n# List all configured servers\ngemini mcp list\n\n# Remove the server\ngemini mcp remove pipeshub\n\n# Temporarily disable/enable\ngemini mcp disable pipeshub\ngemini mcp enable pipeshub\n```\n\n### OAuth Configuration Properties\n\n| Property | Required | Description |\n|---|---|---|\n| `clientId` | Yes | OAuth 2.0 Client ID from PipesHub |\n| `clientSecret` | No | OAuth 2.0 Client Secret (for confidential clients) |\n| `scopes` | No | OAuth scopes to request |\n| `authorizationUrl` | No | Override authorization endpoint (auto-discovered by default) |\n| `tokenUrl` | No | Override token endpoint (auto-discovered by default) |\n| `redirectUri` | No | Override redirect URI (defaults to `http://localhost:7777/oauth/callback`) |\n\n> **Note:** OAuth requires a local browser. It will not work in headless environments, remote SSH without X11 forwarding, or containers without browser access.\n\n

\n\n

Codex CLI

\n\nCodex CLI ([OpenAI Codex](https://developers.openai.com/codex/mcp)) connects to remote MCP servers over **Streamable HTTP**, configured with a `[mcp_servers.]` table in `~/.codex/config.toml` (or `.codex/config.toml` in your project root to scope it per-project). Codex's HTTP transport authenticates with a **bearer token** read from an environment variable, so pass a PipesHub JWT bearer token.\n\n```toml\n[mcp_servers.pipeshub]\nurl = \"PIPESHUB_INSTANCE_URL/mcp\"\nbearer_token_env_var = \"PIPESHUB_BEARER_TOKEN\"\n```\n\n`bearer_token_env_var` is the **name** of the environment variable that holds the token — export it before launching Codex:\n\n```bash\nexport PIPESHUB_BEARER_TOKEN=\"YOUR_BEARER_TOKEN\"\n```\n\n> The token is the raw JWT, without the `Bearer` keyword.\n\nOr add it with the CLI:\n\n```bash\ncodex mcp add pipeshub \\\n --url PIPESHUB_INSTANCE_URL/mcp \\\n --bearer-token-env-var PIPESHUB_BEARER_TOKEN\n```\n\n> `--bearer-token-env-var` takes the **name of the environment variable** holding the token, not the token value itself.\n\n### Verify\n\n```bash\n# List configured MCP servers\ncodex mcp list\n\n# Inside the Codex TUI, view server status and available tools\n/mcp\n```\n\n

\n\n

Claude.ai (Web)

\n\nClaude.ai supports custom connectors via remote MCP servers. This lets you use PipesHub tools directly in the Claude.ai web interface without any local setup.\n\n> **Note:** This feature is currently in beta. Free plan users are limited to one custom connector.\n\n![Claude.ai Connectors Settings](https://raw.githubusercontent.com/pipeshub-ai/mcp-server/main/images/claude-1.png)\n\n![Claude.ai Add Custom Connector Dialog](https://raw.githubusercontent.com/pipeshub-ai/mcp-server/main/images/claude-2.png)\n\n### For Individual Users (Pro / Max Plans)\n\n1. Go to [claude.ai](https://claude.ai) and navigate to **Settings > Connectors**\n2. Click **Add custom connector** at the bottom of the Connectors section\n3. Enter the MCP server URL:\n ```\n PIPESHUB_INSTANCE_URL/mcp\n ```\n4. Click **Advanced settings** and enter your OAuth credentials:\n - **OAuth Client ID**: `YOUR_CLIENT_ID`\n - **OAuth Client Secret**: `YOUR_CLIENT_SECRET`\n5. Click **Add**\n6. You'll be redirected to PipesHub's login page to authenticate and grant permissions\n7. After authenticating, the connector will be active and PipesHub tools will be available in your Claude.ai conversations\n\n### For Team / Enterprise Plans\n\n**Organization Owners** must first add the connector:\n\n1. Navigate to **Organization settings > Connectors**\n2. Click **Add custom connector**\n3. Enter the MCP server URL: `PIPESHUB_INSTANCE_URL/mcp`\n4. Click **Advanced settings** and enter the OAuth Client ID and Client Secret\n5. Click **Add**\n\n**Team members** can then connect:\n\n1. Go to **Settings > Connectors**\n2. Find the PipesHub connector (marked with a \"Custom\" label)\n3. Click **Connect** to authenticate via PipesHub's OAuth login\n\n### Redirect URI\n\nClaude.ai uses the following redirect URI for OAuth:\n\n```\nhttps://claude.ai/api/mcp/auth_callback\n```\n\nRegister this as an allowed redirect URI in your PipesHub OAuth app.\n\n### Security Notes\n\n- Only connect to trusted MCP servers\n- Review the permissions requested during the OAuth authentication flow\n- Claude.ai interacts with PipesHub on your behalf using the granted OAuth token — your password is never shared\n\n

\n\n

LibreChat

\n\nLibreChat supports remote MCP servers with OAuth authentication via its custom connectors UI. This lets you connect PipesHub tools to any model available in your LibreChat instance.\n\n![LibreChat MCP Configuration](https://raw.githubusercontent.com/pipeshub-ai/mcp-server/main/images/librechat.png)\n\n### Configuration\n\n1. Log in to your LibreChat instance\n2. Navigate to **MCP Servers** settings panel\n3. Click **Add** to create a new custom MCP connector\n4. Fill in the connector details:\n - **Name**: `Pipeshub` (or any name you prefer)\n - **MCP Server URL**: `PIPESHUB_INSTANCE_URL/mcp`\n - **Transport**: Select **Streamable HTTPS** \n - **Authentication**: Select **OAuth**\n5. Enter your OAuth credentials:\n - **Client ID**: `YOUR_CLIENT_ID`\n - **Client Secret**: `YOUR_CLIENT_SECRET`\n - **Authorization URL**: `PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize`\n - **Token URL**: `PIPESHUB_INSTANCE_URL/api/v1/oauth2/token`\n - **Scope**: `openid email` (or additional scopes as needed)\n6. Check **I trust this application**\n7. Click **Add** to save the connector\n8. After adding, LibreChat will generate a **Redirect URI** displayed in the connector settings panel (next to the copy button). It follows this format:\n ```\n http://localhost:3080/api/mcp//oauth/callback\n ```\n9. **Copy the Redirect URI** and register it as an allowed redirect URI in your PipesHub OAuth app (see [Step 1](#step-1-create-an-oauth-app-in-pipeshub))\n10. Return to the LibreChat connector and click **Update** to initiate the OAuth flow — you'll be redirected to PipesHub's login page to authenticate and grant permissions\n\n### Redirect URI\n\nLibreChat generates the redirect URI **after** the connector is created. The URI follows this format:\n\n```\nhttp://localhost:3080/api/mcp//oauth/callback\n```\n\nWhere `` is the unique identifier assigned by LibreChat (visible at the top of the connector settings as \"Unique Server Identifier\"). You must copy this URI and add it to your PipesHub OAuth app's allowed redirect URIs **before** authenticating.\n\n> **Note:** If your LibreChat instance runs on a different host or port, the URI will reflect that (e.g., `https://chat.example.com/api/mcp/pipeshub/oauth/callback`).\n\n### Scopes\n\nLibreChat allows you to specify the OAuth scopes in the **Scope** field. Use a space-separated list:\n\n```\nopenid email\n```\n\nTo request PipesHub-specific scopes, add them to the scope field:\n\n```\nopenid email org:read kb:read kb:write semantic:read conversation:read conversation:write conversation:chat agent:read agent:execute\n```\n\n> **Note:** The scopes you request must match the scopes granted to your OAuth app in PipesHub. See [Customizing Default Scopes](#customizing-default-scopes) for details.\n\n

\n\n---\n\n## Local MCP Server (Stdio)\n\nInstead 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.\n\n### Prerequisites\n\n- Node.js 18+ installed\n- A PipesHub instance URL\n- Authentication credentials: either a **Bearer token** (JWT) or **OAuth Client ID + Secret**\n\n### Placeholders\n\nReplace these in all configurations below:\n\n| Placeholder | Description | Example |\n|---|---|---|\n| `PIPESHUB_INSTANCE_URL` | Your PipesHub instance URL | `https://app.pipeshub.com` |\n| `YOUR_BEARER_TOKEN` | JWT Bearer token for authentication | `eyJhbGci...` |\n| `YOUR_CLIENT_ID` | OAuth app client ID | `clid_abc123...` |\n| `YOUR_CLIENT_SECRET` | OAuth app client secret | `clsec_xyz789...` |\n\n

Claude Desktop

\n\nConfigure in Claude Desktop settings (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"command\": \"npx\",\n \"args\": [\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL\",\n \"--bearer-auth\",\n \"YOUR_BEARER_TOKEN\"\n ]\n }\n }\n}\n```\n\nWith OAuth credentials:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"command\": \"npx\",\n \"args\": [\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL\",\n \"--client-id\",\n \"YOUR_CLIENT_ID\",\n \"--client-secret\",\n \"YOUR_CLIENT_SECRET\",\n \"--token-url\",\n \"/api/v1/oauth2/token\"\n ]\n }\n }\n}\n```\n\n

\n\n

Cursor (Local)

\n\nOpen Cursor Settings > Tools and Integrations > New MCP Server, or edit your project's `.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"command\": \"npx\",\n \"args\": [\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL\",\n \"--bearer-auth\",\n \"YOUR_BEARER_TOKEN\"\n ]\n }\n }\n}\n```\n\nWith OAuth credentials:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"command\": \"npx\",\n \"args\": [\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL\",\n \"--client-id\",\n \"YOUR_CLIENT_ID\",\n \"--client-secret\",\n \"YOUR_CLIENT_SECRET\",\n \"--token-url\",\n \"/api/v1/oauth2/token\"\n ]\n }\n }\n}\n```\n\n

\n\n

Claude Code CLI (Local)

\n\n```bash\nclaude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \\\n --server-url PIPESHUB_INSTANCE_URL \\\n --bearer-auth YOUR_BEARER_TOKEN\n```\n\nWith OAuth credentials:\n\n```bash\nclaude mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \\\n --server-url PIPESHUB_INSTANCE_URL \\\n --client-id YOUR_CLIENT_ID \\\n --client-secret YOUR_CLIENT_SECRET \\\n --token-url /api/v1/oauth2/token\n```\n\n

\n\n

Gemini CLI (Local)

\n\n```bash\ngemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \\\n --server-url PIPESHUB_INSTANCE_URL \\\n --bearer-auth YOUR_BEARER_TOKEN\n```\n\nWith OAuth credentials:\n\n```bash\ngemini mcp add pipeshub -- npx -y @pipeshub-ai/mcp start \\\n --server-url PIPESHUB_INSTANCE_URL \\\n --client-id YOUR_CLIENT_ID \\\n --client-secret YOUR_CLIENT_SECRET \\\n --token-url /api/v1/oauth2/token\n```\n\n

\n\n

Codex CLI (Local)

\n\nRun the MCP server as a local stdio process, authenticated with an OAuth app's Client ID and Secret (the `client_credentials` grant). Edit `~/.codex/config.toml` (or `.codex/config.toml` in your project root):\n\n```toml\n[mcp_servers.pipeshub]\ncommand = \"npx\"\nargs = [\n \"-y\",\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL/api/v1\",\n \"--client-id\",\n \"YOUR_CLIENT_ID\",\n \"--client-secret\",\n \"YOUR_CLIENT_SECRET\",\n \"--token-url\",\n \"/api/v1/oauth2/token\",\n]\n```\n\nNotes:\n\n- `--server-url` must include `/api/v1`.\n- `--token-url /api/v1/oauth2/token` is required.\n\nOr authenticate with a JWT bearer token instead:\n\n```toml\n[mcp_servers.pipeshub]\ncommand = \"npx\"\nargs = [\n \"-y\",\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL/api/v1\",\n \"--bearer-auth\",\n \"YOUR_BEARER_TOKEN\",\n]\n```\n\n

\n\n

VS Code

\n\nOpen Command Palette > `MCP: Open User Configuration`, then add:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"command\": \"npx\",\n \"args\": [\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL\",\n \"--bearer-auth\",\n \"YOUR_BEARER_TOKEN\"\n ]\n }\n }\n}\n```\n\n

\n\n

Windsurf

\n\nOpen Windsurf Settings > Cascade > Manage MCPs > View raw config, then add:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"command\": \"npx\",\n \"args\": [\n \"@pipeshub-ai/mcp\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL\",\n \"--bearer-auth\",\n \"YOUR_BEARER_TOKEN\"\n ]\n }\n }\n}\n```\n\n

\n\n

Running from Source (Development)

\n\nTo run the local MCP server from a cloned repository instead of the npm package:\n\n```bash\ngit clone https://github.com/pipeshub-ai/pipeshub-ai.git\ncd pipeshub-ai\nnpm install\nnpm run build\nnode ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN\n```\n\nFor MCP client configuration, replace `npx @pipeshub-ai/mcp` with `node ./bin/mcp-server.js`:\n\n```json\n{\n \"mcpServers\": {\n \"pipeshub\": {\n \"command\": \"node\",\n \"args\": [\n \"./bin/mcp-server.js\",\n \"start\",\n \"--server-url\",\n \"PIPESHUB_INSTANCE_URL\",\n \"--bearer-auth\",\n \"YOUR_BEARER_TOKEN\"\n ]\n }\n }\n}\n```\n\nTo debug with MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector node ./bin/mcp-server.js start --server-url PIPESHUB_INSTANCE_URL --bearer-auth YOUR_BEARER_TOKEN\n```\n\n

\n\n### CLI Help\n\nFor a full list of server arguments:\n\n```bash\nnpx @pipeshub-ai/mcp --help\n```\n\n---\n\n## How It Works\n\n### Architecture\n\n```\nAI Client (Cursor / Claude Code / Gemini CLI / Codex CLI / Claude.ai / LibreChat)\n │\n │ HTTP POST (JSON-RPC)\n │ Authorization: Bearer \n ▼\n PIPESHUB_INSTANCE_URL/mcp\n │\n │ StreamableHTTP Transport\n │ (stateless, per-request MCP server)\n ▼\n PipesHub API (curated tool set — see TOOLS.md)\n```\n\n\n### OAuth Protected Resource Discovery\n\nPipesHub exposes OAuth protected resource discovery at:\n\n```\nPIPESHUB_INSTANCE_URL/.well-known/oauth-protected-resource/mcp\n```\n\nThis returns all OAuth endpoints automatically:\n- Authorization: `PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize`\n- Token: `PIPESHUB_INSTANCE_URL/api/v1/oauth2/token`\n- Revocation: `PIPESHUB_INSTANCE_URL/api/v1/oauth2/revoke`\n- JWKS: `PIPESHUB_INSTANCE_URL/.well-known/jwks.json`\n\n---\n\n## Troubleshooting\n\n### \"Incompatible auth server: does not support dynamic client registration\"\nThis means the client is trying dynamic registration instead of using your pre-configured credentials. Make sure you passed `--client-id` and `--client-secret` (Claude Code) or the `auth` object (Cursor) correctly.\n\n### Authentication fails / redirect error\n- Ensure the **Redirect URI** in your OAuth app matches exactly what the client uses:\n - **Cursor**: `cursor://anysphere.cursor-mcp/oauth/callback`\n - **Claude Code**: `http://localhost:/callback`\n - **Claude.ai**: `https://claude.ai/api/mcp/auth_callback`\n - **Gemini CLI**: `http://localhost:7777/oauth/callback`\n - **LibreChat**: `http://localhost:3080/api/mcp//oauth/callback`\n- Make sure the OAuth app is **active** (not suspended) in PipesHub\n\n### Cannot reach MCP endpoint\n- Verify the endpoint is accessible: `curl -X POST PIPESHUB_INSTANCE_URL/mcp` (should return 401, not connection error)\n- Check that your PipesHub instance has MCP enabled\n\n### Debugging with MCP Inspector\n```bash\nnpx @modelcontextprotocol/inspector\n```\nThen connect to `PIPESHUB_INSTANCE_URL/mcp` with a Bearer token to test the endpoint directly.\n\n---\n\n## FAQ\n\n

How do I update the scopes for my MCP integration?

\n\n1. **Update the [`MCP_SCOPES`](https://github.com/pipeshub-ai/pipeshub-ai/blob/main/backend/env.template#L57) environment variable** on your PipesHub instance to include the new scopes you want exposed via the discovery endpoint.\n2. **Update the OAuth app scopes** in PipesHub: go to **Settings > Developer Settings > OAuth Apps**, select your OAuth app, and add or remove scopes as needed.\n3. **Re-authenticate the client** — existing tokens carry the old scopes, so you need to re-authenticate to get a new token with the updated scopes. For example:\n - **Cursor**: Remove and re-add the MCP server, or clear the cached OAuth token and reconnect.\n - **Claude Code**: Run `/mcp` and complete the browser login flow again.\n - **Gemini CLI**: Run `/mcp auth pipeshub` to re-authenticate.\n - **Codex CLI**: Update `PIPESHUB_BEARER_TOKEN` with a fresh token and restart Codex.\n - **Claude.ai**: Disconnect and reconnect the connector in **Settings > Connectors**.\n\n

\n\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_97":98,"_99":-5,"_100":101,"_102":103,"_104":105,"_106":107},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_95":82,"_96":82},"ratingAvg","reviewCount","topics",[],"license","language","TypeScript","registryName","io.github.pipeshub-ai/mcp","homepage","https://docs.pipeshub.com/for-agents","packages",[108],{"_109":110,"_111":112,"_72":73},"registryType","npm","identifier","@pipeshub-ai/mcp","ENV",{"_115":116,"_117":118,"_119":120},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]