地图能力接进智能体，过去要自己封装 REST API、处理签名、适配返回结构。高德官方把路径规划、POI 检索这些能力直接封装成标准 MCP 服务，客户端只管连接和调用。本文用 Python + LangChain 走一遍完整接入，重点放在三类高频报错的定位上。
两种接入方式怎么选
官方提供 SSE 远程接入和 NodeJS 本地接入两条路。前者服务端由高德维护，本地零部署，HTTP 长连接实时拿到最新工具集；后者要自己跑 Node 环境，调试成本高一截，只在需要深度定制或私有化时才值得选。日常开发选 SSE，没什么犹豫的。
客户端工具也别用 Cursor 一键注册那种高度封装的路径——逻辑黑盒，出错没处下手。langchain-mcp-adapters 适配库自己写客户端，几十行代码，问题都在明面上。
密钥配置：环境变量是底线
高德开放平台注册账号、实名认证、新建应用选「服务端 API」，拿到 AMap Key。Key 直接写进脚本是最常见的泄露源——被人扒走恶意调用，扣的是你的配额。标准做法是 .env 文件加 python-dotenv：
pip install langchain-mcp-adapters langchain python-dotenv
AMAP_KEY=你的高德开发者密钥
AMAP_MCP_URL=高德MCP官方SSE服务地址
.env 必须进 .gitignore——比硬编码更隐蔽的坑是密钥跟着代码一起提交进了仓库。
客户端核心代码
import asyncio
import os
from dotenv import load_dotenv
from langchain_mcp_adapters.client import MultiServerMCPClient
load_dotenv()
async def init_amap_mcp_client():
mcp_config = {
"amap-service": {
"url": os.getenv("AMAP_MCP_URL"),
"transport": "sse",
"headers": {
"Authorization": f"Bearer {os.getenv('AMAP_KEY')}"
}
}
}
async with MultiServerMCPClient(mcp_config) as client:
tools = client.get_tools()
print(f"成功加载高德MCP工具数量：{len(tools)}")
for tool in tools:
print(f"{tool.name} | {tool.description}")
return client, tools
if __name__ == "__main__":
asyncio.run(init_amap_mcp_client())
三类报错的定位顺序
新手跑不通，基本落在这三处，按顺序排查：
一，异步没等待。 get_tools() 是异步方法，直接调用拿不到结果，必须 asyncio.run() 包外层。报错特征是返回 coroutine 对象或者事件循环相关异常。
二，协议没声明。 配置里必须显式写 "transport": "sse"，缺了客户端不知道用什么方式跟远程服务说话，连接阶段就挂。
三，鉴权失败。 401 类报错先查环境变量是否真的加载（打印一下而不是猜），再确认 Key 对应的应用有没有开通对应服务权限——权限没开，Key 再对也是白搭。
接上之后的验收
连接成功只是第一步，验收要看三样：工具数量与官方文档对得上、随机挑一个工具传真实参数能返回合理结果、断网重连后工具列表能自动恢复。这三条过了，才能把客户端交给上层智能体做工具路由。
这套链路的真正优势在维护侧：高德服务端新增或修改工具，本地代码一行不动，重跑一遍加载就能同步。对要长期运行的智能体服务来说，这比接入方式本身更值钱。
评论0