当前位置：首页 > news >正文

把本地 MCP 工具临时暴露给 AI 客户端：用 cpolar 排查 Resource 为什么看不到

news 2026/7/20 18:05:24

把本地 MCP 工具临时暴露给 AI 客户端：用 cpolar 排查 Resource 为什么看不到

搞了一个本地 MCP Server，规规矩矩注册了两个 Resource，本地跑起来一切正常。结果接到 AI 客户端一看——Resource 列表空空如也，一个都看不到。

这个问题在 MCP 开发者社区里太常见了，掘金上甚至有一条热帖就在问同一件事。原因通常不是 Resource 注册错了，而是客户端和服务器的网络链路没走通——尤其是当你的 MCP Server 跑在 SSE 或 Streamable HTTP 传输层上时，客户端无法主动回连到你的本地端口，resources/list请求根本没有到达服务器。

这篇就记录一个我自己的排查办法：用 cpolar 给本地 MCP Server 开一个临时公网地址，让 AI 客户端能直接回调进来，看看 Resource 列表到底有没有正常暴露。

1 什么场景下 Resource 会"看不到"

先明确一下这篇文章要解决的具体问题。

你的 MCP Server 可以长这样——用 Python FastMCP 或者 TypeScript SDK 写的一个服务器，在本地监听一个 HTTP 端口：

from mcp.server.fastmcp import FastMCP mcp = FastMCP("demo-server") @mcp.resource("config://app/settings") def get_settings() -> str: """返回应用配置项""" return "theme=dark\nlanguage=zh-CN\nmax_items=50" @mcp.resource("docs://help/about") def get_about() -> str: """返回关于页面内容""" return "# About\n\nThis is a demo MCP server." if __name__ == "__main__": mcp.run(transport="sse")

启动之后，服务器在http://localhost:8000/sse上等客户端连进来。

问题出在：当你把 MCP Server 配成 Streamable HTTP 或 SSE 模式时，客户端和服务器是双向通信的。客户端需要先连接到你的 SSE 端点，服务器才能通过这个长连接把 Resource 列表推回去。如果客户端在另一台机器上、或者在 Docker 容器里、或者在 AI Studio 的云端运行时里——它连不上你的localhost:8000，resources/list请求就永远发不出来。

这不是 Resource 注册错了，这是网络链路没打通。

2 环境准备：先确认本地能跑通

在动手暴露到公网之前，先确认本地环境一切正常。这一步花不了两分钟，但能帮你后面少走很多弯路。

2.1 确认 MCP Server 正常启动

终端执行：

python mcp_demo_server.py

看到类似这样的输出：

INFO: Started server process [12345] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://localhost:8000

说明服务器已经在本地 8000 端口上监听 SSE 连接了。

2.2 用 curl 快速验证 SSE 端点

开另一个终端，执行：

curl -N http://localhost:8000/sse

正常情况下你会看到 SSE 的初始化事件输出，类似：

event: endpoint data: /message?session_id=abc123 event: initialized data: {}

如果你看到Connection refused或者curl: (52) Empty reply from server，说明服务器本身就没起来，先回去修，不要急着往外穿透。

2.3 用 MCP Inspector 本地测一次 Resource

官方 MCP Inspector 是排查这类问题最趁手的工具：

npx @modelcontextprotocol/inspector

打开浏览器访问http://localhost:5173，在连接方式里选 "Streamable HTTP"，地址填http://localhost:8000/sse。连接成功后，点Resources标签页，你应该能看到刚才注册的两个 Resource。

这一轮本地测试过了，说明 Resource 注册本身没有问题。那为什么 AI 客户端看不见？多半是客户端那端连不回来。

3 用 cpolar 给 MCP Server 生成公网地址

本地确认正常，下一步就是让 AI 客户端能连到你的 MCP Server。你要做的不是改代码，也不是重写 Resource，而是在中间加一个公网跳板，让客户端能把回调请求发进来。

3.1 安装 cpolar

如果你机器上还没装 cpolar，按平台选一个命令：

macOS（Homebrew）：

brew install cpolar

Linux（一键脚本）：

curl -L https://www.cpolar.com/static/downloads/install-release-cpolar.sh | sudo bash

Windows：

去官网下载页面 https://www.cpolar.com/download 下载 Windows 安装包，双击安装。

3.2 注册并获取 token

cpolar 需要一个 token 来绑定你的账号。注册地址：

https://dashboard.cpolar.com

注册完成后进入仪表盘，在Auth Token页面复制你的 token，然后在终端执行：

cpolar authtoken 你的token

这条命令会把 token 写入配置文件，后续启动隧道时自动带上。

3.3 启动 HTTP 隧道

MCP Server 刚才监听的是 8000 端口，cpolar 对 HTTP 隧道要映射的就是这个端口：

cpolar http 8000

命令执行后终端会停留在前台，输出类似：

Forwarding https://abc123.cpolar.cn -> http://localhost:8000 Forwarding http://abc123.cpolar.cn -> http://localhost:8000 Web Interface http://127.0.0.1:9200

看到这一行，说明隧道已经建成了。https://abc123.cpolar.cn就是你 MCP Server 的临时公网地址。

注意：这个地址是 cpolar 免费套餐生成的随机地址，24 小时内会变化。这篇文章只做临时调试用，用完之后关掉即可。如果后续需要长期固定地址，考虑基础套餐的固定二级子域名。

3.4 验证公网地址能访问 MCP Server

用公网地址替换掉本机地址，再跑一遍 curl：

curl -N https://abc123.cpolar.cn/sse

如果能看到和之前一样的 SSE 事件输出，恭喜，公网链路已经打通了。如果返回 404 或者连接超时，先检查：

MCP Server 是否还在运行
隧道是否显示online
防火墙是否放行了 8000 端口

检查隧道状态最方便的方式是打开http://127.0.0.1:9200，在 Web UI 里看隧道是否在线。

4 让 AI 客户端通过公网地址连接并验证 Resource

公网地址到手了，现在让 AI 客户端用这个地址去连 MCP Server。

4.1 配置客户端连接地址

不同的 MCP 客户端配置方式不一样，这里列两个最常见的场景：

Claude Desktop（或同类本地客户端）：

在claude_desktop_config.json中，把 MCP Server 的配置改为：

{ "mcpServers": { "demo-server": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/inspector", "--connect", "https://abc123.cpolar.cn/sse" ] } } }

自定义 MCP Client（Python）：

from mcp import ClientSession from mcp.client.sse import sse_client async def test_resources(): async with sse_client("https://abc123.cpolar.cn/sse") as streams: async with ClientSession(streams[0], streams[1]) as session: await session.initialize() resources = await session.list_resources() for r in resources: print(f" {r.name}: {r.uri}")

4.2 验证 Resource 列表

连接成功后，在客户端里请求 Resource 列表。如果能看到你注册的那两个 Resource，说明问题不在代码，在网络——之前本地看不到纯粹是客户端连不回来。

如果公网地址连上去之后 Resource 列表仍然为空，那问题就出在服务器端的 Resource 注册逻辑上了。这个时候需要回来检查：

4.3 Resource 不可见的常见原因

原因 1：capabilities 声明缺失

MCP 协议要求服务器在 initialize 阶段声明自己支持 Resource。检查你的服务器初始化代码是否正确声明了resourcescapability。如果用 FastMCP，通常 SDK 会自动做这件事；但如果你自己实现底层协议，很容易漏掉。

原因 2：Resource URI 格式不对

Resource 的 URI 必须符合 RFC 3986 规范。一个常见的踩坑是用了config://这样的 scheme。MCP 协议本身没有强制限定 scheme，但客户端通常只会稳定渲染自己支持的 URI 形态。实际排查下来，大部分"看不到"的问题出在客户端不支持非标准 scheme 的渲染，而不是 Resource 注册失败。

原因 3：list_resources handler 没返回

如果用低层 SDK，需要手动实现list_resources回调：

# 低层写法，容易忘记返回完整的 resource 列表 @server.list_resources() async def handle_list_resources(): return [ Resource( uri="config://app/settings", name="App Settings", description="应用配置参数", mimeType="text/plain" ), Resource( uri="docs://help/about", name="About Page", description="关于页面内容", mimeType="text/markdown" ) ]

检查确认你确实返回了Resource对象列表，而不只是打印了日志。

原因 4：SSE 长连接断开了

MCP 的 SSE 传输层依赖持久化长连接。如果网络不稳定、客户端重连太频繁、或者 cpolar 隧道因为闲置超时而被回收，SSE 连接就会断开。遇到这种情况，重启隧道后重新连接即可。

5 通过 cpolar 4040 检查回调链路

如果连着公网地址但 Resource 还是看不到，还有一个排查手段：cpolar 提供的 4040 请求检查面板。

启动隧道时，cpolar 同时在本地启动了http://127.0.0.1:4040作为 HTTP 检查界面。打开这个地址，你能看到 cpolar 接收到的每一次 HTTP 请求的详情，包括：

请求路径和方法
请求头（包括Mcp-Session-Id）
请求体（JSON-RPC 消息内容）

这个面板在排查"客户端到底有没有发resources/list请求过来"这个问题时特别好用。

具体来说：让 AI 客户端发起一次 Resource 列表请求，然后切到 4040 页面看看有没有对应的POST /message请求到达。如果有，说明网络链路没问题；如果没有，说明客户端根本没成功建立连接。

# 直接在浏览器打开 open http://127.0.0.1:4040

在请求列表里搜索resources/list的关键字，如果能找到，就把响应体里的result和本地 MCP Inspector 测出来的结果对比一下。

6 验证完成后关闭隧道

MCP Resource 排查结束之后，第一件事就是关掉 cpolar 隧道。临时调试隧道不需要长期运行，关掉的方式很简单：

在 cpolar 前台窗口按Ctrl + C，终端会提示隧道已关闭。

确认隧道已经离线的办法：刷新http://127.0.0.1:9200，在线隧道列表如果空了，说明已经全部关停。

安全提醒：这篇文章全程操作的都是测试 Resource，不包含任何敏感数据（没有 API Key、没有数据库密码、没有用户信息）。如果是排查生产环境的 MCP Server，不要在公网上暴露管理端口，不要传入真实凭证，确认完成后立刻断网。
cpolar 生成的是随机临时地址，非长期固定地址，而且隧道关了地址立刻失效，安全风险可控。但也正是这个原因，它特别适合做 MCP 调试场景——用完即弃。