
我第一次跑高德 MCP 的官方示例时,卡了半小时,原因特别蠢:get_tools() 少写了一个 await。程序不报错,只是打印出来一串 coroutine 对象,工具一个都没加载。后来盯着输出看了两遍才反应过来。
这一步容易翻车。
把整个流程重新捋一遍,把容易踩的坑一次说清。
最容易吞掉人的坑:异步方法没等结果
langchain-mcp-adapters 的 MultiServerMCPClient,get_tools() 是异步方法,必须 await。直接调用拿到的是一个还没执行的协程对象,len() 会直接抛异常,或者循环打印时输出一堆不可读的东西。
正确的骨架是这样:
import asyncio, os
from dotenv import load_dotenv
from langchain_mcp_adapters.client import MultiServerMCPClient
load_dotenv(override=True)
async def main():
cfg = {
"amap": {
"url": os.getenv("AMAP_MCP_URL"),
"transport": "sse",
"headers": {"Authorization": f"Bearer {os.getenv('AMAP_KEY')}"},
}
}
async with MultiServerMCPClient(cfg) as client:
tools = await client.get_tools()
print(f"工具数量: {len(tools)}")
for t in tools:
print(t.name)
asyncio.run(main())
三处必须严丝合缝:transport 显式写 sse,get_tools() 前面加 await,外层用 asyncio.run() 驱动。少任何一处,现象都不同但都很迷惑。
密钥配置的静默失效
密钥在高德开放平台注册后创建应用、选服务端 API 类型就能拿到。真正的坑不在获取,在加载。
我推荐环境变量而不是写在代码里,这个不用争论。但有一步很多人漏了:load_dotenv() 默认不覆盖已经存在的系统环境变量。我在这上面耗了二十分钟——系统里残留了一个旧的 AMAP_KEY,.env 里的新值怎么都不生效,鉴权一直 401。加上 override=True 才解决。
还有一个变体:.env 文件里值带了引号,部分版本的解析器会把引号当值的一部分。拿到 401 时,先打印 os.getenv("AMAP_KEY") 确认读到的字符串干不干净,比反复换 Key 快得多。
为什么我选 SSE 远程接入
高德官方给了两条路:SSE 直连远程服务,或者本地部署 NodeJS 版本。我推荐 SSE 远程接入而不是本地部署,理由很实际:本地部署意味着自己维护 Node 环境、跟版本、处理兼容性,而地图能力这种相对稳定的服务,自己维护一层的收益接近于零。
但 SSE 方案也有两个要在生产里提前想清楚的风险。
一个是网关超时。SSE 是长连接,公司内网常见 Nginx 默认 proxy_read_timeout 60 秒,空闲连接会被掐断,现象是每隔一分钟报一次连接重置。走网关部署时要把这个超时调大,或者让客户端做指数退避重连。
另一个是配额。个人开发者 Key 有每秒和每日的调用上限,智能体高频调用地图工具时很容易撞线,返回配额超限错误。做批量任务前先算一下单次任务的工具调用次数,必要时在客户端加节流。
先确认权限再压测,别反着来。
怎么判定真的接通了
光看到工具列表打印出来,不算通。我的验收是三层:
第一层,len(tools) 打印出来数量在十几个以上,说明鉴权和拉取都正常——工具数量异常少通常是权限没开全,而不是网络问题。
第二层,挑一个读接口(比如地理编码)真实调用一次,传入明确地址,看返回结构里的解析结果是否为空。这一步验证的是端到端,包括参数传递。
第三层,连续调用十次,确认没有间歇性的鉴权失败。配额类问题在低频测试里藏不住,但间歇超时能暴露出来。
三层都过,才算接通。整个流程我完整跑过一遍,从拿 Key 到三层验收通过,顺利的话半小时以内;卡住基本都卡在密钥加载和 await 这两处,跟协议本身关系不大。

评论0