1. 先搞清楚我们要搭的这条链路Agent 这个词听起来玄乎拆开看其实就三件事一个会思考的大模型、一堆能干活的外部工具、一个把两者串起来的协议。MCPModel Context Protocol就是那个协议它让大模型能像插 U 盘一样接入外部数据源。高德地图 MCP Server 则是把地理编码、路径规划、周边搜索这些能力封装成标准接口Agent 调用它就能拿到真实的景点坐标和路线数据。这篇教程面向的是零基础 Agent 开发者你不需要懂什么 RAG、Function Calling 底层原理只要会复制粘贴配置文件、能跑几条命令就行。最终我们要交付的东西很具体一个能对话的 Agent你告诉它「帮我规划杭州三日游」它自动调用高德地图 MCP 拉取景点和路线然后生成一个可以直接在浏览器打开的旅行攻略网页。整个链路里有两个关键节点需要提前准备好。第一是高德开放平台的应用 Key这个去高德官网申请就行免费额度够个人开发用。第二是大模型的 API 通道这里我用 TaoToken 来统一接入原因是它兼容 OpenAI 格式的接口规范配置起来省事而且一个 Key 可以切换不同模型调试 Agent 的时候不用来回改环境变量。你可能会问为什么不用本地模型实测下来Agent 场景对模型的指令遵循能力要求比较高本地小模型在解析 MCP 返回的 JSON 结构时经常出错导致工具调用失败。用 API 通道虽然有一点成本但调试效率高很多等流程跑通了再考虑换模型也不迟。下面我会按「配环境 → 写配置 → 启动 Agent → 验证调用 → 排错」的顺序一步步来每一步都有可复制的代码和命令。你跟着做半小时内应该能看到攻略网页跑起来。2. TaoToken 前置准备拿 Key 和确认通道在配置 MCP 之前先把大模型的 API 通道准备好。TaoToken 的接入方式跟 OpenAI 兼容你只需要一个 API Key 和一个 Base URL 就能调通。2.1 获取 API Key打开 TaoToken 官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册登录后进入控制台。在左侧菜单找到「API Keys」页面点「创建新 Key」给它起个名字比如agent-travel-demo权限选默认的即可。创建完成后复制那串sk-开头的 Key注意它只显示一次先粘贴到记事本里存着。如果你之前没用过这类服务可以把它理解成一个「模型网关」你的 Agent 代码只认一个 Base URL 和一个 Key具体背后调的是哪个模型在请求参数里指定就行。这样切换模型不用改代码只改一个字符串。2.2 确认 API 通道地址TaoToken 的 API 基础地址是https://taotoken.net/api注意这个地址后面不加 UTM 参数直接用在代码里。完整的请求端点就是https://taotoken.net/api/v1/chat/completions跟 OpenAI 的格式完全一致。你可以先用 curl 测一下通道是否通curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的Key \ -d { model: gpt-4o-mini, messages: [{role: user, content: 回复ok}], max_tokens: 10 }如果返回的 JSON 里choices[0].message.content有内容说明通道没问题。这一步很重要因为后面 Agent 调 MCP 的时候如果模型通道不通报错信息会混在一起很难排查。2.3 申请高德地图 Key高德开放平台的应用创建流程不复杂登录后进「应用管理」→「我的应用」→「创建新应用」应用类型选「Web 服务」然后添加 Key。创建完你会拿到一个 32 位的字符串这就是AMAP_MAPS_API_KEY。注意高德 MCP Server 用的是 Web 服务类型的 Key不是 Web 端JS API的 Key选错了调用会返回INVALID_USER_SCODE错误。这个坑我踩过当时排查了半天以为是 MCP 配置问题其实是 Key 类型不对。3. 可复制的 MCP 配置文件骨架现在进入核心部分。MCP 的配置本质上就是告诉 Agent「有一个叫 amap-maps 的工具你用 npx 启动它启动的时候把高德 Key 传进去」。不同 Agent 客户端的配置文件位置不一样但结构大同小异。3.1 通用 MCP 配置骨架先看最核心的配置块你可以直接复制{ mcpServers: { amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: 你申请的高德Key } } } }这段配置的含义是Agent 启动时会执行npx -y amap/amap-maps-mcp-server这个命令把高德 Key 通过环境变量传进去。-y参数表示自动确认安装避免 npx 卡在交互提示上。如果你用的是 Claude Code 或类似的客户端配置文件通常叫settings.json或mcp.json放在项目根目录的.claude或.config文件夹下。下面是一个完整的settings.json示例把 TaoToken 的模型通道和高德 MCP 放在一起{ model: { provider: openai, baseUrl: https://taotoken.net/api, apiKey: sk-你的TaoToken Key, modelName: gpt-4o-mini }, mcpServers: { amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: 你的高德Key } } } }这里baseUrl填https://taotoken.net/api不要加/v1因为客户端会自动拼接路径。modelName可以先填gpt-4o-mini等流程跑通后你可以换成更强的模型来提升攻略生成质量。3.2 环境变量方式推荐把 Key 写在配置文件里有泄露风险尤其是你要把代码传到 Git 仓库的时候。更稳妥的做法是用环境变量export TAOTOKEN_API_KEYsk-你的Key export AMAP_MAPS_API_KEY你的高德Key然后配置文件里改成引用变量{ mcpServers: { amap-maps: { command: npx, args: [-y, amap/amap-maps-mcp-server], env: { AMAP_MAPS_API_KEY: ${AMAP_MAPS_API_KEY} } } } }不同客户端对环境变量语法的支持不一样有的用${VAR}有的用$VAR具体看你用的工具文档。如果启动时报「env not found」先检查语法。3.3 验证 MCP Server 能否独立启动在接入 Agent 之前先单独跑一下 MCP Server确认它能正常启动AMAP_MAPS_API_KEY你的高德Key npx -y amap/amap-maps-mcp-server如果看到类似MCP server running on stdio的输出说明 Server 本身没问题。如果报command not found: npx先装 Node.js建议 18 以上版本。如果报401或INVALID_USER_SCODE回去检查高德 Key 的类型和是否启用了 Web 服务。这一步能帮你把「MCP Server 本身的问题」和「Agent 接入的问题」分开排错效率高很多。4. 启动 Agent 并调用高德 MCP 的逐步验证配置写好了接下来要验证整条链路能不能跑通。我建议分三步走先确认 Agent 能连上模型再确认能列出 MCP 工具最后跑一个完整的旅行攻略生成任务。4.1 第一步确认 Agent 能连上 TaoToken启动你的 Agent 客户端以 Claude Code 为例在对话里输入请用一句话介绍你自己并告诉我你当前使用的模型名称。如果 Agent 正常回复说明 TaoToken 通道配置正确。如果报401 Unauthorized检查 API Key 是否复制完整如果报model not found检查modelName拼写。4.2 第二步确认 MCP 工具已加载在对话里输入列出你当前可用的所有 MCP 工具并说明每个工具的作用。正常情况下Agent 会返回类似这样的工具列表工具名作用maps_geocode地址转经纬度maps_regeocode经纬度转地址maps_search_poi关键词搜索 POImaps_around_search周边搜索maps_direction_driving驾车路径规划maps_direction_walking步行路径规划maps_weather天气查询如果 Agent 说「没有可用工具」或只列出了内置工具说明 MCP 配置没生效。常见原因是配置文件路径不对或者客户端没有重启。改完配置一定要完全退出客户端再重新打开热重载有时候不生效。4.3 第三步跑一个完整的旅行攻略任务这是最关键的一步。在对话里输入下面这段提示词用高德地图 MCP 帮我规划一个杭州三日游攻略要求 1. 第一天西湖周边第二天西溪湿地宋城第三天灵隐寺龙井村 2. 每天给出具体的景点顺序、建议游玩时间、交通方式 3. 查询每个景点的经纬度坐标 4. 最后生成一个 HTML 旅行攻略网页包含地图链接和行程表格Agent 的执行过程大致是这样的先调用maps_search_poi搜索「西湖」「西溪湿地」等关键词拿到 POI ID 和坐标再调用maps_direction_driving或maps_direction_walking计算景点之间的路线最后把结果整理成 HTML。你会在终端里看到类似这样的工具调用日志[Tool Call] maps_search_poi({ keywords: 西湖, city: 杭州 }) [Tool Result] { poi_id: B023B0..., location: 120.15,30.25, name: 西湖风景名胜区 } [Tool Call] maps_direction_walking({ origin: 120.15,30.25, destination: 120.13,30.26 }) [Tool Result] { distance: 1200, duration: 18, steps: [...] }如果工具调用成功返回了数据但 Agent 最后没有生成 HTML可能是模型的输出长度限制到了。这时候可以在提示词里加一句「先输出行程数据再单独生成 HTML 代码」分两步走。4.4 渲染攻略网页Agent 生成的 HTML 代码通常会直接输出在对话里你把它复制出来存成travel-guide.html双击就能在浏览器打开。如果 Agent 支持写文件你也可以让它直接保存请把刚才生成的 HTML 保存到当前目录的 travel-guide.html 文件里。打开网页后你应该能看到一个包含行程表格、景点坐标、路线距离的攻略页面。表格里每一行对应一个景点包含到达时间、游玩时长、交通方式。如果页面样式比较简陋可以让 Agent 再调一版「给这个页面加上卡片式布局和渐变背景」。到这里整条链路就跑通了TaoToken 提供模型能力 → Agent 解析指令 → 调用高德 MCP 拿数据 → 生成 HTML 攻略页。5. 本篇常见错误排查跑不通的时候别慌大部分问题集中在下面几个地方。我按报错信息分类整理你对号入座。5.1 MCP Server 启动失败报错Error: Cannot find module amap/amap-maps-mcp-server说明 npx 没拉到包。先检查网络能不能访问 npm registry然后手动跑一次npx -y amap/amap-maps-mcp-server看能否安装。如果卡住不动可能是 npm 源的问题换成国内镜像npm config set registry https://registry.npmmirror.com报错AMAP_MAPS_API_KEY is required说明环境变量没传进去。检查配置文件里env字段的 Key 名是否拼写正确注意大小写敏感。5.2 高德接口返回错误码INVALID_USER_SCODEKey 类型不对去高德控制台确认应用是「Web 服务」类型。DAILY_QUERY_OVER_LIMIT当日调用量超了个人开发者免费额度是每天 5000 次调试阶段一般够用。如果超了等第二天重置或者去控制台看能不能提额。INVALID_PARAMS传的参数格式不对比如经纬度写成了120.15, 30.25中间有空格高德要求120.15,30.25这种紧凑格式。5.3 Agent 不调用 MCP 工具有时候 Agent 会「忘记」自己有 MCP 工具直接用自己的知识回答。这时候在提示词里明确要求「必须调用 maps_search_poi 工具查询真实坐标不要凭记忆编造」。如果还是不行检查客户端的 MCP 开关是否打开有些客户端默认不启用 MCP。5.4 TaoToken 通道报错401 UnauthorizedKey 错了或者过期了去控制台重新生成一个。429 Too Many Requests请求频率超了等几秒重试或者在代码里加个重试逻辑。model not found模型名拼错了去 TaoToken 的模型列表页确认一下可用模型名称。不同通道支持的模型不一样别照搬 OpenAI 的模型名。5.5 生成的 HTML 打不开或样式错乱如果 HTML 里引用了外部 CDN 的 CSS 或 JS断网环境下会加载失败。让 Agent 把样式写成内联的style标签不依赖外部资源。如果表格列数对不上检查 Agent 输出的 HTML 里td和th数量是否一致这种小错误手动改一下就行。6. 继续往下走把 Demo 变成常用工具跑通这个 Demo 之后你可以做几件事让它更实用。第一把常用的旅行城市做成模板每次只改城市名和天数Agent 就能复用同一套提示词。第二把生成的 HTML 攻略页部署到静态托管服务上分享给朋友直接打开链接就能看。第三如果你经常做行程规划可以考虑用 Coding Plan 把整个流程封装成一个命令行工具输入「杭州 3 天」就自动生成网页。接入文档里还有更多 MCP 工具的用法比如天气查询可以加到攻略里提示「第三天有雨建议带伞」距离测量可以算景点之间的步行时间。这些组合起来你的旅行攻略网页会越来越像一个小型产品。如果你在配置过程中遇到报错优先去 API Keys 页面确认 Key 状态再去接入文档对照配置格式。大部分问题都是 Key 类型不对或者配置文件路径写错耐心对一遍就能解决。
