菜单

把远程 MCP server 接进 Claude 和 Cursor,以及连不上时该查什么

2026-11-03MCP Checkup

把一个远程 MCP server 加进 Claude 或 Cursor,一分钟就够了。可连不上的时候,报错很少告诉你为什么。这篇讲两个客户端各自怎么加,以及连不上时按什么顺序排查。

步骤是 2026 年 10 月 25 日对照两家官方文档核对的,11 月 6 日又核对了一次。两边的界面都改得勤,你看到的菜单名如果和这里不一样,以官方页面为准,链接在文末。

开始之前:连接是从哪里发出的

大多数连不上的情况,都出在这个区别上。

  • Claude 是从 Anthropic 的云端连接,不是从你的电脑。 所有 Claude 客户端都是这样,Claude Desktop 也一样。你的 server 必须能从公网访问。跑在 localhost 上、在 VPN 后面或在内网里的 server,都连不上。如果 server 在防火墙后面,要放行 Anthropic 的出站地址段:2026 年 11 月 6 日是 160.79.104.0/21 和 153.61.208.0/20(IPv4),最新的列表在 Anthropic 的 IP addresses 页面。
  • 在你电脑上用的 Cursor,从你的电脑连接。 Cursor 自己的示例配置指向的就是 http://localhost:3000/mcp。所以只有你这台机器访问得到的 server,在 Cursor 里能用,在 Claude 里不行。Cursor 的 Cloud Agents 是例外:它们的登录状态保存在 Cursor 的服务器上。

所以「在 Cursor 里能用」说明的东西比看上去少。加进 Claude 之前,先确认 server 从你的网络外面也能应答。

加进 Claude

Free、Pro、Max、Ultra:

  1. 打开 Customize → Connectors。
  2. 点 + Add,再点 Add custom connector。
  3. 填一个名字和 server 的地址,比如 https://your-server.example/mcp,点 Continue。
  4. Claude 会显示它检测到的登录方式。在 Authentication 里选 Sign in now、Sign in when needed 或 No sign in。
  5. server 用 OAuth 的话,选一个 OAuth client:Claude 公开的身份(推荐的默认项)、自动注册,或者你自己的 client。
  6. server 要的是固定的 API key 或 bearer token 的话,加在 Request headers 里。
  7. 点 Add。

Free 账号只能加一个自定义连接器。Team 和 Enterprise 由所有者在 Organization settings → Connectors 里添加(Add → Custom → Web),成员再到 Customize → Connectors 里点它旁边的 Connect。

在对话里使用时,点输入框左下角的 +,打开 Connectors,为这个对话打开它。要改连接器的地址或设置,得先删掉再重新添加。

加进 Cursor

Cursor 从一个 JSON 文件里读取 MCP server:

  • 项目里的 .cursor/mcp.json,只对这个项目生效;
  • 用户主目录下的 ~/.cursor/mcp.json,对所有项目生效。

远程 server 就是一个名字加一个 url:

{
  "mcpServers": {
    "my-server": {
      "url": "https://your-server.example/mcp"
    }
  }
}

server 要固定 token 的话,加 headers。密钥放在环境变量里,别写进文件:

{
  "mcpServers": {
    "my-server": {
      "url": "https://your-server.example/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVER_TOKEN}"
      }
    }
  }
}

远程 server 也可以用 OAuth,Cursor 支持动态客户端注册;不支持动态注册的服务,可以在 auth 对象里给 Cursor 一个固定的 client ID。配置好以后,在侧边栏的 Customize 里打开这个 server。想看发生了什么,打开 Output 面板(Cmd+Shift+U),选 MCP Logs,里面有握手、工具调用和错误信息。

连不上时,按这个顺序查

1. 地址对不对,外面能不能访问? 要用完整的端点路径(比如 /mcp,不能只写域名)。在你的网络之外的机器上,或者用手机热点,发一个客户端连上来时发的第一个请求:

curl -sS -i https://your-server.example/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H 'mcp-protocol-version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"connect-test","version":"1"}}}'

正常的 server 会回 HTTP 200,带一个写明协议版本的 JSON-RPC 结果;需要登录的话,会回 401。超时、DNS 报错或返回一个 HTML 页面,说明客户端走到这一步也会停住。

2. 它要不要凭据,怎么要? 401 应该带一个 WWW-Authenticate 头,指向 server 的受保护资源元数据。客户端靠这个指引,才知道该带你去哪里登录。没有它,客户端只能去试 well-known 的元数据地址;那里也没有的话,就没有地方可以登录,只剩固定请求头这一条路,前提是 server 支持。401 与受保护资源元数据那篇里,每一步都有 curl 命令。在我们探测器对每个被追踪的 server 过去三天里最新的一轮检测中,5,924 个里有 1,944 个要先拿到凭据才肯列出工具(读取时间 2026 年 10 月 25 日 19:51 UTC)。所以要登录是常事,不代表出了问题。

3. 它用的是不是当前的传输方式? Cursor 支持 Streamable HTTP(向上面那个端点发 POST),也支持更早的 HTTP+SSE。Claude 的帮助页面没写用哪种。现行规范里是 Streamable HTTP,就用它。如果你的 server 还只提供 /sse 端点,见从 SSE 迁到 Streamable HTTP。

4. tools/list 有没有回来? 客户端连上了却看不到工具,说明握手成功了,后面某一步没成。上线前怎么测试 MCP server 用 curl 把握手之后的每一步都走了一遍,可以逐步对照。

5. 看客户端自己的日志;改完要重新添加。 Cursor 的日志在 Output 面板的 MCP Logs 里。Claude 的连接器不能原地编辑,改了 server 的地址或登录设置之后,要删掉连接器再重新添加。

先从外面看一眼

如果 server 不是你写的,或者在排查自己的配置之前想先有个外部视角,可以在 MCP Checkup 上搜它。我们的探测器从公网连接,不带任何凭据,和云端客户端在你登录之前看到的情况差不多。报告会显示 server 有没有应答、协商的是哪个协议版本、要不要凭据以及怎么要、列出了哪些工具。报告记录的是我们观察到的情况,不是对 server 的评判。

文中用到的官方文档(2026 年 10 月 25 日、11 月 6 日核对):

  • Claude Help Center:"Getting started with custom connectors using remote MCP"
  • Anthropic:"IP addresses"(platform.claude.com/docs/en/api/ip-addresses)
  • Cursor Docs:"Model Context Protocol (MCP)"(cursor.com/docs/context/mcp)