CLIENT INTEGRATION · v1.0

客户端接入指南

平台在 streamable-http 模式下会把你的 MCP Server 暴露成两个端点。本指南按客户端类型给出接入步骤,以及如何用工具验证连接。

一、两种 URL 怎么选

启动 Server 后,平台会返回:

{
  "server_id": "1_my-agent_aBcD3FgH7iJ",
  "mcp_server_url":  "https://<your-host>/mcp/1_my-agent_aBcD3FgH7iJ",
  "mcp_client_url":  "/sse/1_my-agent_aBcD3FgH7iJ",
  "mcp_client_url_streamable": "/mcp/1_my-agent_aBcD3FgH7iJ"
}

端点	协议	推荐用于
`/mcp/<server_id>`	Streamable HTTP	Cherry Studio / Cursor / 通用 MCP 客户端(2025+)
`/sse/<server_id>`	SSE (Server-Sent Events)	Claude Desktop 旧版 / 仅支持 SSE 的桌面客户端

优先用 Streamable HTTP(/mcp/...):MCP 官方推荐的传输方式,支持双向流、断线重连,效率更高。仅当客户端明确说不支持 Streamable HTTP 时,才退到 SSE。

二、Claude Desktop

Claude Desktop 偏好 stdio 模式(本地进程),所以推荐用下载的 zip 在本地跑,而不是连远程 URL。

方式 A:stdio(推荐)

在控制台第 3 步选 stdio 传输模式,点击「生成 MCP Server」
下载 zip,解压到任意目录(如 ~/mcp-servers/my-agent/)
编辑 Claude 桌面客户端的配置文件:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

添加 Server 配置:

{
  "mcpServers": {
    "my-agent": {
      "command": "python",
      "args": ["~/mcp-servers/my-agent/mcp_server.py"],
      "env": {
        "USER_API_ENDPOINT": "https://api.example.com",
        "API_KEY": "sk-xxx"
      }
    }
  }
}

重启 Claude Desktop,工具列表里应能看到 my-agent 暴露的所有工具

方式 B:连远程 URL

新版 Claude Desktop 桌面客户端(MCP 0.5+)支持把远程 URL 当作 MCP Server 添加,但需要客户端主动配置 HTTP 头部鉴权。如果你用这种模式,平台目前不替你做头部注入(因为 Claude 桌面端是用户本地信任边界),建议改用方式 A。

三、Cherry Studio

Cherry Studio 是国产 AI 客户端,MCP 集成做得很好,直接用 SSE URL。

打开 Cherry Studio → 设置 → MCP Servers
添加 Server,类型选 SSE
URL 填平台返回的 mcp_client_url(即 /sse/<server_id> 前补 host):
```
https://<your-host>/sse/1_my-agent_aBcD3FgH7iJ
```
保存,回到对话页启用这个 MCP Server。工具列表应自动刷新出来

为什么 Cherry Studio 用 SSE:Cherry Studio 早期版本基于 SSE 实现 MCP 集成,Streamable HTTP 适配在后续版本加入。如果你的 Cherry Studio 版本够新(v1.0+),建议改为填 /mcp/<id> URL 以获得更好的性能。

四、Cursor

Cursor(0.40+)原生支持 MCP,使用 Streamable HTTP。

打开 Cursor → Settings → Features → Model Context Protocol

点击「Add new global MCP server」,填:

{
  "mcpServers": {
    "my-agent": {
      "url": "https://<your-host>/mcp/1_my-agent_aBcD3FgH7iJ"
    }
  }
}

重启 Cursor,打开 Composer(Agent 模式),工具列表里应能看到 my-agent 下的所有工具

注意:Cursor 对 HTTP 头部鉴权的支持有限。如果你的 MCP Server 走 api_key 鉴权,X-API-Key 头由 MCP Server 内部注入(转给业务 API 时用),不需要在 Cursor 端配置。

五、通用 Streamable HTTP 客户端

任何遵循 MCP 规范、实现 Streamable HTTP 传输的客户端都可以接入。最小集成示例(Python,使用官方 mcp SDK):

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

SERVER_URL = "https://<your-host>/mcp/1_my-agent_aBcD3FgH7iJ"

async def main():
    async with streamablehttp_client(SERVER_URL) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            for t in tools.tools:
                print(f"- {t.name}: {t.description}")
            # 调用工具示例
            result = await session.call_tool(
                "search_products",
                {"query": "iPhone", "limit": 5}
            )
            print(result)

import asyncio
asyncio.run(main())

Node.js / 其他语言参考 MCP 官方文档。

六、用 REST 工具验证连接

在连客户端之前,先用 curl 确认 Server 至少能响应 MCP 协议初始化请求:

curl -i -X POST https://<your-host>/mcp/<server_id> \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "curl-test", "version": "0.1"}
    }
  }'

正常响应应该返回 HTTP 200,body 是包含 serverInfo / capabilities 的 JSON-RPC 响应。

401/403/404 都说明有问题:401 是 Session 过期(重新登录);404 是 server_id 不存在或 Server 已被停止;403 几乎不会发生(平台不限制跨用户的 URL 读取,只靠 token 段防猜)。

七、Server 状态与生命周期

通过 server_id 你可以查询 Server 状态(认证 cookie 必须带上):

# 状态查询
GET /api/v1/run/<server_id>/status
→ {"server_id":"...","status":"running","url":"/sse/...","config":{...}}

# 停止
DELETE /api/v1/run/<server_id>
→ {"server_id":"...","status":"stopped"}

# 列出自己的所有 Server
GET /api/v1/run
→ [{server_id, status, config, url}, ...]

Server 一旦被停止,对应 /mcp/<id> 和 /sse/<id> 立刻 404——客户端会自动重连失败,提示用户重新启用。

八、跨域 / 防火墙

如果你的客户端在浏览器里(如 Web 版的 Cherry Studio),平台需要允许跨域 cookie。生产环境部署时确认:

平台域名与客户端域名满足 CORS(配置在 .env 的 CORS_ALLOWED_ORIGINS)
Session cookie agentbridge_session 在跨站请求时被发送(SameSite=Lax 默认行为)

桌面客户端(Claude Desktop / Cherry Studio 桌面 / Cursor)不存在跨域问题,直接连即可。