高德MCP接入避坑:密钥、报错与验证全流程

文章配图

我第一次跑高德 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

评论0

请先
显示验证码
没有账号?注册  忘记密码?