PipesHub

Cursor 支持通过 mcp.json 中的 auth 对象为远程 MCP 服务配置静态 OAuth。

配置

打开 Cursor Settings > Tools and Integrations > New MCP Server，或编辑项目的 .cursor/mcp.json：

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "auth": {
        "CLIENT_ID": "YOUR_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

Cursor 会通过 PipesHub 的 /.well-known/oauth-protected-resource/mcp 元数据自动发现授权和令牌端点。

注意：如果省略 scopes 字段，Cursor 会获取 /.well-known/oauth-protected-resource/mcp，并请求其中列出的所有 scopes_supported。如需限制访问，请仅明确列出所需范围。你也可以在服务端控制公开哪些范围——请参阅自定义默认范围。

使用环境变量

使用 Cursor 的 ${env:VAR} 插值，避免将密钥存储在配置文件中：

{
  "mcpServers": {
    "pipeshub": {
      "url": "${env:PIPESHUB_INSTANCE_URL}/mcp",
      "auth": {
        "CLIENT_ID": "${env:PIPESHUB_CLIENT_ID}",
        "CLIENT_SECRET": "${env:PIPESHUB_CLIENT_SECRET}",
        "scopes": [
          "kb:read", "kb:write",
          "semantic:read", "semantic:write",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write",
          "config:read", "user:read"
        ]
      }
    }
  }
}

重定向 URI

Cursor 为所有 MCP 服务使用固定的重定向 URI：

cursor://anysphere.cursor-mcp/oauth/callback

在 PipesHub 中创建 OAuth 应用时，将此 URI 注册为允许的重定向 URI。

OAuth 登录故障排除

如果 Cursor 的内置浏览器无法加载 OAuth 登录页面，请从内置浏览器中复制授权 URL，并粘贴到常用浏览器中以完成登录流程。

Claude Code 支持通过 --client-id、--client-secret 和 --callback-port 使用静态 OAuth 凭据连接远程 HTTP MCP 服务。

PipesHub 在 /.well-known/oauth-protected-resource/mcp 提供发现信息，因此 Claude Code 会自动发现授权端点和令牌端点。

重要： Claude Code 不支持配置特定的 scope。它会获取 /.well-known/oauth-protected-resource/mcp，读取 scopes_supported 列表，并请求其中的所有 scope。PipesHub 只会列出 MCP 工具使用的 scope。请为 OAuth 应用配置所有这些 scope：登录时会授予应用允许的 scope；缺少所需 scope 的工具将无法使用；如果应用不允许其中任何 scope，登录将因 invalid_scope 而失败。要查看或限制此列表，请参阅自定义默认 Scope。

使用 CLI 添加

claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

--client-secret 未提供值时，会提示输入并隐藏输入内容。若要跳过提示，请设置 MCP_CLIENT_SECRET 环境变量：

MCP_CLIENT_SECRET=YOUR_CLIENT_SECRET claude mcp add --transport http \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

若要在所有项目中使用：

claude mcp add --transport http --scope user \
  --client-id YOUR_CLIENT_ID \
  --client-secret \
  --callback-port 8080 \
  pipeshub PIPESHUB_INSTANCE_URL/mcp

使用 JSON 添加

claude mcp add-json pipeshub '{
  "type": "http",
  "url": "PIPESHUB_INSTANCE_URL/mcp",
  "oauth": {
    "clientId": "YOUR_CLIENT_ID",
    "callbackPort": 8080
  }
}' --client-secret

项目范围配置（.mcp.json）

在项目根目录中创建 .mcp.json 文件。此文件可以提交到版本控制（通过环境变量避免将密钥存入文件）：

{
  "mcpServers": {
    "pipeshub": {
      "type": "http",
      "url": "${PIPESHUB_INSTANCE_URL}/mcp",
      "oauth": {
        "clientId": "${PIPESHUB_CLIENT_ID}",
        "callbackPort": 8080
      }
    }
  }
}

启动 Claude Code 前设置环境变量：

export PIPESHUB_INSTANCE_URL="https://app.pipeshub.com"
export PIPESHUB_CLIENT_ID="your-client-id"

注意： 客户端密钥存储在系统密钥链中，而非配置文件中。首次通过 /mcp 进行身份验证时，系统会提示你输入该密钥。

身份验证

添加服务后，在 Claude Code 中运行 /mcp，并按照浏览器登录流程操作。令牌会安全存储并自动刷新。

验证

claude mcp list
claude mcp get pipeshub

Gemini CLI 通过 dynamic_discovery（默认方式）支持使用 OAuth 连接远程 MCP 服务，可自动从 PipesHub 的 /.well-known/oauth-protected-resource/mcp 发现授权端点和令牌端点。

选项 A：设置文件

编辑 ~/.gemini/settings.json：

{
  "mcpServers": {
    "pipeshub": {
      "url": "PIPESHUB_INSTANCE_URL/mcp",
      "oauth": {
        "clientId": "YOUR_CLIENT_ID",
        "clientSecret": "YOUR_CLIENT_SECRET",
        "scopes": [
          "org:read", "org:write", "org:admin",
          "user:read", "user:write", "user:invite", "user:delete",
          "usergroup:read", "usergroup:write",
          "team:read", "team:write",
          "kb:read", "kb:write", "kb:delete", "kb:upload",
          "semantic:read", "semantic:write", "semantic:delete",
          "conversation:read", "conversation:write", "conversation:chat",
          "agent:read", "agent:write", "agent:execute",
          "connector:read", "connector:write", "connector:sync", "connector:delete",
          "config:read", "config:write",
          "document:read", "document:write", "document:delete",
          "crawl:read", "crawl:write", "crawl:delete"
        ]
      }
    }
  }
}

注意： 调整 scopes 列表，使其与 OAuth 应用获准的 scope 相匹配。如果只需要部分工具，可以相应地限制 scope。

选项 B：CLI 命令

gemini mcp add --transport http pipeshub PIPESHUB_INSTANCE_URL/mcp

然后编辑 ~/.gemini/settings.json，添加上文所示的 oauth 块。

身份验证

在 Gemini CLI 中使用 /mcp auth 命令：

# List servers and their auth status
/mcp auth

# Authenticate with PipesHub (opens browser for login)
/mcp auth pipeshub

# Re-authenticate if tokens expire
/mcp auth pipeshub

首次连接时，Gemini 会自动检测 401 响应，发现 OAuth 端点并打开浏览器供你登录。令牌会安全存储在 ~/.gemini/mcp-oauth-tokens.json 中并自动刷新。

管理服务

# List all configured servers
gemini mcp list

# Remove the server
gemini mcp remove pipeshub

# Temporarily disable/enable
gemini mcp disable pipeshub
gemini mcp enable pipeshub

Codex CLI（OpenAI Codex）通过 Streamable HTTP 连接到远程 MCP 服务，在 ~/.codex/config.toml 中使用 [mcp_servers.<name>] 表进行配置（也可以在项目根目录的 .codex/config.toml 中配置，以限定在该项目内使用）。Codex 的 HTTP 传输通过从环境变量读取 Bearer 令牌进行身份验证，因此请传入 PipesHub JWT Bearer 令牌。

[mcp_servers.pipeshub]
url = "PIPESHUB_INSTANCE_URL/mcp"
bearer_token_env_var = "PIPESHUB_BEARER_TOKEN"

bearer_token_env_var 是存放令牌的环境变量的名称，请在启动 Codex 前导出该变量：

export PIPESHUB_BEARER_TOKEN="YOUR_BEARER_TOKEN"

令牌是原始 JWT，不包含 Bearer 关键字。

也可以通过 CLI 添加：

codex mcp add pipeshub \
  --url PIPESHUB_INSTANCE_URL/mcp \
  --bearer-token-env-var PIPESHUB_BEARER_TOKEN

--bearer-token-env-var 接收的是存放令牌的环境变量名称，而不是令牌值本身。

验证

# List configured MCP servers
codex mcp list

# Inside the Codex TUI, view server status and available tools
/mcp

Claude.ai 支持通过远程 MCP 服务添加自定义连接器。这样，你无需进行任何本地设置，即可直接在 Claude.ai 网页界面中使用 PipesHub 工具。

注意： 此功能目前处于 Beta 阶段。免费套餐用户最多只能添加一个自定义连接器。

个人用户（Pro / Max 套餐）

1. 前往 claude.ai，然后进入 设置 > 连接器
2. 点击连接器部分底部的 添加自定义连接器
3. 输入 MCP 服务 URL：

   PIPESHUB_INSTANCE_URL/mcp
   

4. 点击 高级设置，并输入 OAuth 凭据：
   • OAuth 客户端 ID：YOUR_CLIENT_ID
   • OAuth 客户端密钥：YOUR_CLIENT_SECRET
5. 点击 添加
6. 系统会将你重定向到 PipesHub 登录页面，以进行身份验证并授予权限
7. 完成身份验证后，连接器即会启用，PipesHub 工具也会在你的 Claude.ai 对话中提供

团队 / 企业套餐

组织所有者必须先添加连接器：

1. 前往 组织设置 > 连接器
2. 点击 添加自定义连接器
3. 输入 MCP 服务 URL：PIPESHUB_INSTANCE_URL/mcp
4. 点击 高级设置，并输入 OAuth 客户端 ID 和客户端密钥
5. 点击 添加

然后，团队成员即可连接：

1. 前往 设置 > 连接器
2. 找到 PipesHub 连接器（标有“自定义”标签）
3. 点击 连接，通过 PipesHub 的 OAuth 登录进行身份验证

重定向 URI

Claude.ai 使用以下 OAuth 重定向 URI：

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

请将其注册为 PipesHub OAuth 应用中允许使用的重定向 URI。

安全说明

• 仅连接到可信的 MCP 服务
• 查看 OAuth 身份验证流程中请求的权限
• Claude.ai 使用已授予的 OAuth 令牌代表你与 PipesHub 交互，不会共享你的密码

LibreChat 支持通过自定义连接器界面使用 OAuth 身份验证连接远程 MCP 服务。这样，你可以将 PipesHub 工具连接到 LibreChat 实例中提供的任意模型。

配置

1. 登录您的 LibreChat 实例
2. 前往 MCP Servers 设置面板
3. 点击 Add，创建新的自定义 MCP 连接器
4. 填写连接器详情：
   • Name：Pipeshub（或您喜欢的任意名称）
   • MCP Server URL：PIPESHUB_INSTANCE_URL/mcp
   • Transport：选择 Streamable HTTPS
   • Authentication：选择 OAuth
5. 输入您的 OAuth 凭据：
   • Client ID：YOUR_CLIENT_ID
   • Client Secret：YOUR_CLIENT_SECRET
   • Authorization URL：PIPESHUB_INSTANCE_URL/api/v1/oauth2/authorize
   • Token URL：PIPESHUB_INSTANCE_URL/api/v1/oauth2/token
   • Scope：openid email（或根据需要添加其他作用域）
6. 勾选 I trust this application
7. 点击 Add 保存连接器
8. 添加后，LibreChat 会生成一个 Redirect URI，显示在连接器设置面板中（复制按钮旁边）。其格式如下：

   http://localhost:3080/api/mcp/<server-identifier>/oauth/callback
   

9. 复制 Redirect URI，并将其注册为 PipesHub OAuth 应用中允许的重定向 URI（参见步骤 1）
10. 返回 LibreChat 连接器并点击 Update，以启动 OAuth 流程 — 您将被重定向到 PipesHub 登录页面进行身份验证并授予权限

重定向 URI

LibreChat 会在创建连接器后生成重定向 URI。URI 格式如下：

http://localhost:3080/api/mcp/<server-identifier>/oauth/callback

其中，<server-identifier> 是 LibreChat 分配的唯一标识符（显示在连接器设置顶部的 "Unique Server Identifier" 中）。您必须复制此 URI，并在进行身份验证之前将其添加到 PipesHub OAuth 应用的允许重定向 URI 中。

注意： 如果您的 LibreChat 实例运行在不同的主机或端口上，URI 也会相应变化（例如，https://chat.example.com/api/mcp/pipeshub/oauth/callback）。

作用域

LibreChat 允许您在 Scope 字段中指定 OAuth 作用域。请使用以空格分隔的列表：

openid email

若要请求 PipesHub 专属作用域，请将其添加到作用域字段中：

openid email org:read kb:read kb:write semantic:read conversation:read conversation:write conversation:chat agent:read agent:execute

注意： 登录时只会授予 PipesHub 中 OAuth 应用允许的所请求作用域，因此请请求该应用已获授权的作用域。详情请参阅自定义默认作用域。

在 Claude Desktop 设置中配置（claude_desktop_config.json）：

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

打开 Cursor Settings > Tools and Integrations > New MCP Server，或编辑项目的 .cursor/mcp.json：

{
  "mcpServers": {
    "pipeshub": {
      "command": "npx",
      "args": [
        "@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 \
  --bearer-auth YOUR_BEARER_TOKEN

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

使用你的个人访问令牌，将 MCP 服务作为本地 stdio 进程运行。编辑 ~/.codex/config.toml（或项目根目录下的 .codex/config.toml）：

[mcp_servers.pipeshub]
command = "npx"
args = [
  "-y",
  "@pipeshub-ai/mcp",
  "start",
  "--server-url",
  "PIPESHUB_INSTANCE_URL",
  "--bearer-auth",
  "YOUR_BEARER_TOKEN",
]

打开命令面板 > MCP: Open User Configuration，然后添加：

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

打开 Windsurf Settings > Cascade > Manage MCPs > View raw config，然后添加：

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

如需从克隆的仓库运行本地 MCP 服务，而非使用 npm 包：

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

配置 MCP 客户端时，将 npx @pipeshub-ai/mcp 替换为 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"
      ]
    }
  }
}

使用 MCP Inspector 进行调试：

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

1. 在 PipesHub 实例上更新 MCP_SCOPES 环境变量，使其包含你希望客户端获取的作用域。发现功能只会列出 MCP 工具使用的作用域。
2. 在 PipesHub 中更新 OAuth 应用的作用域：前往 设置 > 开发者设置 > OAuth 应用，选择你的 OAuth 应用，然后按需添加或移除作用域。
3. 重新对客户端进行身份验证——现有令牌仍携带旧作用域，因此你需要重新进行身份验证，以获取具有更新后作用域的新令牌。例如：
   • Cursor：移除并重新添加 MCP 服务，或清除缓存的 OAuth 令牌后重新连接。
   • Claude Code：运行 /mcp 并再次完成浏览器登录流程。
   • Gemini CLI：运行 /mcp auth pipeshub 以重新进行身份验证。
   • Codex CLI：将 PIPESHUB_BEARER_TOKEN 更新为新令牌，然后重启 Codex。
   • Claude.ai：在 设置 > 连接器 中断开并重新连接该连接器。