1. 当 ArcGIS Enterprise 遇上 Spatial Agent：MCP 通道为什么总在鉴权上翻车
如果你正在把 ArcGIS Enterprise 或者自建的空间分析服务接进 AI Agent，大概率会遇到一个很具体的场景：Agent 已经能理解“查一下这个片区 500 米内的学校”，但真正去调 GIS 能力时，卡在了 MCP 服务端的 endpoint 和鉴权配置上。这不是模型不够聪明，而是 MCP 通道没打通。
MCP（Model Context Protocol）在这里扮演的角色，是让 AI Agent 以标准化方式发现并调用 GIS 能力。它不替代 ArcGIS Enterprise 的 REST API、Feature Service 或 Geoprocessing Service，而是在这些已有能力之上加一层面向 Agent 的工具描述和调用机制。问题在于，很多团队把 MCP 服务端写好后，endpoint 指向的是内网地址，鉴权用的是硬编码 token，一旦要统一管理多个 GIS 服务、多个 Agent 入口，Key 就散落在各个配置文件里，改一次要动五六个地方。
这篇内容面向的是已经在做 GIS 平台接入 Spatial Agent 的开发者。我会给出把 MCP 服务端 endpoint 与鉴权改到 TaoToken 的可复制配置片段，用一次空间查询请求验证调用链是否贯通，最后把常见的 401、local proxy failed、reading choices 这类报错逐个拆开。目标很明确：让 GIS 的 AI 入口具备统一 Key 管理能力，而不是每接一个 Agent 就重新配一遍鉴权。
TaoToken 在这里的作用是统一 Key 管理入口。你可以在 https://taotoken.net/api 拿到 API 地址，在 https://taotoken.net/api-keys 生成 Key，然后在 MCP 服务端的配置里把 Base URL 和 Key 统一指向它。这样无论是 ArcGIS Enterprise 的 Portal 内容搜索、图层描述，还是自建的空间分析服务，都走同一套鉴权，Agent 侧不需要感知每个 GIS 服务的独立 token。
我试过把三个不同的 GIS 服务端（一个 ArcGIS Enterprise 的 Feature Service、一个自建的 GeoJSON 查询接口、一个 GP Service 包装层）统一挂到同一个 MCP 配置下，改 Key 只需要动一个环境变量。下面按步骤来。
2. TaoToken 前置：MCP 服务端 endpoint 与鉴权统一到一处
在动手改配置之前，先把 TaoToken 这一侧准备好。你需要两样东西：API 地址和 API Key。API 地址是 https://taotoken.net/api，Key 在 https://taotoken.net/api-keys 生成。注意这里不要加 UTM 参数，API 调用地址保持干净。
MCP 服务端的配置通常分两部分：一是 MCP Server 本身的启动配置，告诉 Agent 去哪里找这个 MCP 服务；二是 MCP Server 内部调用 GIS 能力时的鉴权配置，也就是它拿什么 Key 去访问 ArcGIS Enterprise 或自建服务。我们要改的是第二部分，让 MCP Server 不再直接持有 GIS 服务的原始 token，而是统一走 TaoToken。
这里有一个关键设计：MCP Server 对 Agent 暴露的是 Tool 列表，比如search_portal_content、describe_layer、query_data、geocode、route_analysis。Agent 不关心这些 Tool 背后是 ArcGIS Enterprise 还是自建服务，它只按 Tool Schema 构造调用。而 MCP Server 在执行这些 Tool 时，需要向真正的 GIS 服务发请求。这个请求的 Base URL 和鉴权头，就是我们要统一到 TaoToken 的地方。
如果你用的是 Claude Code 或者类似的编码 Agent 来调试 MCP 配置，可以在 Claude Code 的 settings 里把 MCP Server 的启动命令和参数写清楚。Claude Code 的配置路径通常是~/.claude/settings.json或者项目级的.claude/settings.json。下面会给一个可复制的 JSON 片段。
对于 Cline 这类支持 MCP 的编辑器插件，配置方式类似，通常在cline_mcp_settings.json里写 MCP Server 的 command、args 和 env。env 里放 TaoToken 的 Base URL 和 Key，这样 MCP Server 启动时就能读到。
Codex 的 auth.json 则是另一套。如果你用 Codex 来跑 Agent 任务，auth.json 里需要写 Base URL、Key 和 Model ID 三件套。这三件套在后面的配置片段里会具体给出。
先把 TaoToken 的 Key 拿到手，然后我们进入配置环节。记住一个原则：MCP Server 的 env 里只放 TaoToken 的 Key，不放 ArcGIS Enterprise 的原始账号密码。GIS 服务的鉴权由 TaoToken 这一层统一代理和转发，MCP Server 不需要知道每个 GIS 服务的独立凭证。
3. 可复制配置：MCP Server 的 JSON/TOML/settings 片段
这一节给三份配置，分别对应 Claude Code 的 settings、Cline 的 MCP settings、以及 Codex 的 auth.json。你可以按自己用的工具选一份，也可以三份都留着对照。
先看 Claude Code 的 settings.json。路径是~/.claude/settings.json，如果你只想对当前项目生效，就放在项目根目录的.claude/settings.json。内容如下：
{ "mcpServers": { "gis-spatial-agent": { "command": "npx", "args": [ "-y", "@your-org/gis-mcp-server@latest", "--transport", "stdio" ], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-your-taotoken-key", "GIS_PORTAL_URL": "https://your-arcgis-enterprise/portal", "GIS_MCP_TOOLSET": "portal_search,describe_layer,query_data,geocode,route_analysis" } } } }这里TAOTOKEN_BASE_URL和TAOTOKEN_API_KEY是 MCP Server 内部调用 GIS 能力时统一使用的鉴权入口。GIS_PORTAL_URL是你的 ArcGIS Enterprise Portal 地址，MCP Server 用它来搜索 Portal 内容。GIS_MCP_TOOLSET控制暴露哪些 Tool，先只开查询和描述类，写操作后面再逐步放开。
再看 Cline 的 MCP settings。文件通常叫cline_mcp_settings.json，放在 Cline 的配置目录下。内容结构类似：
{ "mcpServers": { "gis-spatial-agent": { "command": "node", "args": [ "/path/to/gis-mcp-server/dist/index.js" ], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-your-taotoken-key", "GIS_PORTAL_URL": "https://your-arcgis-enterprise/portal", "GIS_MCP_TOOLSET": "portal_search,describe_layer,query_data" }, "disabled": false, "autoApprove": [ "search_portal_content", "describe_layer" ] } } }autoApprove里只放只读类 Tool，query_data虽然也是读，但涉及具体数据返回，建议先手动确认。等调用链稳定后再考虑加进去。
最后是 Codex 的 auth.json。路径通常在~/.codex/auth.json。这里需要写全 Base URL、Key 和 Model ID 三件套：
{ "base_url": "https://taotoken.net/api", "api_key": "sk-your-taotoken-key", "model": "claude-sonnet-4-20250514", "provider": "taotoken" }Model ID 按你实际用的模型填，这里只是示例。Codex 用这个 auth.json 来调模型，而 MCP Server 的配置是另一份，两者不要混在一起。Codex 负责 Agent 的推理和工具选择，MCP Server 负责实际执行 GIS Tool。
如果你用的是 TOML 格式的配置，比如某些 Rust 写的 MCP 客户端，结构如下：
[mcp_servers.gis-spatial-agent] command = "npx" args = ["-y", "@your-org/gis-mcp-server@latest", "--transport", "stdio"] [mcp_servers.gis-spatial-agent.env] TAOTOKEN_BASE_URL = "https://taotoken.net/api" TAOTOKEN_API_KEY = "sk-your-taotoken-key" GIS_PORTAL_URL = "https://your-arcgis-enterprise/portal" GIS_MCP_TOOLSET = "portal_search,describe_layer,query_data"三份配置的核心逻辑一致：MCP Server 启动时从 env 读取 TaoToken 的 Base URL 和 Key，所有对 GIS 服务的调用都经过这一层。这样你换 Key 只需要改一个地方，不用去动 ArcGIS Enterprise 的账号配置。
配置改完后，重启 MCP Server 和 Agent 客户端。接下来验证调用链。
4. 验证请求：一次空间查询走通 MCP 调用链
配置写好了，怎么确认真的通了？不要一上来就让 Agent 做复杂任务，先用一个最小空间查询请求验证。我建议分三步：先验证 MCP Server 能启动并列出 Tool，再验证 Portal 内容搜索能返回结果，最后验证一次带空间范围的 query_data 能拿到要素。
第一步，启动 MCP Server 并列出 Tool。如果你用的是 stdio 传输，可以直接在终端跑：
TAOTOKEN_BASE_URL=https://taotoken.net/api \ TAOTOKEN_API_KEY=sk-your-taotoken-key \ GIS_PORTAL_URL=https://your-arcgis-enterprise/portal \ npx -y @your-org/gis-mcp-server@latest --transport stdio --list-tools预期输出是一个 JSON 数组，包含search_portal_content、describe_layer、query_data等 Tool 名称和参数 Schema。如果这里报 401，说明 TaoToken Key 没读到或者格式不对，检查 env 变量名是否和 MCP Server 代码里读的一致。
第二步，在 Agent 里发一个内容搜索请求。比如在 Claude Code 里输入：
搜索 Portal 中带有 mcp 标签的 Feature Service，关键词是 schoolAgent 会调用search_portal_content，MCP Server 向 ArcGIS Enterprise Portal 发请求。预期返回一个列表，包含 Item ID、标题、类型、URL。如果返回空列表，先确认 Portal 里确实有打了mcp标签的项目，因为 MCP 的内容搜索机制用标签来控制哪些项目进入 Agent 可见范围。
第三步，做一次带空间范围的查询。先让 Agent 描述图层：
描述一下这个 Feature Service 的图层结构，Item ID 是 xxxxxAgent 调用describe_layer，返回字段列表、字段类型、别名、空间参考、范围。确认字段语义后，再发查询：
查询这个图层中，在指定范围内、类型为学校的要素，返回名称和坐标Agent 会构造query_data调用，MCP Server 把空间范围和字段条件转成 GIS 服务能理解的请求。预期返回若干要素，每个要素有名称和几何坐标。
如果第三步成功返回了要素，说明整条链路贯通了：Agent 理解任务 → 选择 Tool → MCP Server 鉴权走 TaoToken → 调用 ArcGIS Enterprise → 返回空间数据 → Agent 组织结果。这时候你可以把同一个 MCP 配置复制到其他 Agent 入口，Key 不用改。
验证模型本身是否正常响应，可以在 https://taotoken.net/models 里直接对话测试。如果模型对话正常但 MCP Tool 调用失败，问题就在 MCP 配置或 GIS 服务侧，不在模型。
5. 常见报错排查：401、local proxy failed、reading choices、OAuth
这一节把实际踩过的坑列出来，对照报错找原因。
401 Unauthorized。最常见。三种可能：TaoToken Key 没填对、Key 过期、或者 MCP Server 读 env 的变量名和配置里写的不一致。先检查TAOTOKEN_API_KEY是否以sk-开头，再确认 MCP Server 代码里读的是不是这个变量名。如果 Key 没问题，看请求头是不是Authorization: Bearer sk-xxx，有些 MCP Server 默认用X-API-Key，需要改成 Bearer。
local proxy failed。这个报错通常出现在 MCP Server 尝试连接 GIS 服务时，网络层没通。检查GIS_PORTAL_URL是否可达，ArcGIS Enterprise 是否允许来自 MCP Server 所在机器的请求。如果是内网服务，确认 MCP Server 和 GIS 服务在同一网络区域。另外检查 TaoToken Base URL 是否写成了https://taotoken.net/api，不要多写斜杠或路径。
reading choices 相关报错。这类报错一般出现在 Agent 侧解析模型返回时，模型返回的结构和 Agent 预期的不一致。常见原因是 Model ID 填错，或者 auth.json 里的 provider 配置和实际用的模型不匹配。检查 Codex auth.json 里的model字段是否是你实际有权限调用的模型，base_url是否指向https://taotoken.net/api。如果用的是 Claude Code，检查 settings 里有没有冲突的模型配置。
OAuth 相关报错。ArcGIS Enterprise 如果开了 OAuth 认证，MCP Server 直接拿 TaoToken Key 去调可能会被拒。这时候需要在 TaoToken 这一侧配置好对 GIS 服务的转发规则，或者在 MCP Server 里加一层 token 交换逻辑。简单做法是先用 ArcGIS Enterprise 的长期 token 在 TaoToken 侧做映射，MCP Server 只认 TaoToken Key。如果报错信息里出现invalid_token或OAuth token expired，先确认 GIS 服务侧的 token 是否还有效。
Tool 列表为空。MCP Server 启动了，但 Agent 看不到任何 Tool。检查GIS_MCP_TOOLSET环境变量是否拼写正确，逗号分隔有没有多余空格。另外确认 MCP Server 的版本是否支持你写的 Tool 名称，有些旧版本只暴露search和query两个 Tool。
query_data 返回空结果但没报错。空间查询的条件可能太严，或者坐标系不匹配。先让 Agent 调describe_layer确认空间参考，再检查查询范围用的坐标系是否和图层一致。ArcGIS Enterprise 的 Feature Service 通常支持inSR和outSR参数，MCP Server 应该帮你处理了，但如果自建服务没处理，需要手动指定。
排查顺序建议：先看 MCP Server 日志，确认请求有没有发出去；再看 TaoToken 侧的调用记录，确认鉴权有没有过；最后看 GIS 服务日志，确认空间查询有没有执行。三层日志对照，基本能定位到具体哪一环断了。
6. 统一 Key 之后：GIS 的 AI 入口怎么长期维护
调用链贯通只是第一步。真正让 GIS 的 AI 入口稳定跑下去，需要把 Key 管理、Tool 治理和日志追溯这三件事固定下来。
Key 管理方面，TaoToken 的统一 Key 让你只需要维护一个凭证。但建议按环境分 Key：开发环境一个、测试环境一个、生产环境一个。MCP Server 的 env 里通过TAOTOKEN_API_KEY读取，不同环境用不同的启动脚本注入。这样即使开发环境的 Key 泄露，也不会影响生产。
Tool 治理方面，不要一次性把所有 GIS 能力都暴露给 Agent。先从只读类 Tool 开始：search_portal_content、describe_layer、query_data、geocode。等这些稳定运行一段时间后，再考虑加route_analysis和自定义 GP Tool。写操作类 Tool，比如创建要素、修改属性、发布服务，建议长期保持手动确认，不要放进autoApprove。
日志追溯方面，MCP Server 侧要记录每次 Tool 调用的入参和出参，TaoToken 侧有调用记录，GIS 服务侧有访问日志。三份日志用同一个 request ID 串起来，出问题时能快速定位。Agent 侧的任务日志也要保留，知道用户提了什么任务、Agent 选了哪个 Tool、最终返回了什么结果。
如果你需要长期跑编码类或 Agent 类任务，可以考虑用 Coding Plan 来管理调用额度，地址是 https://taotoken.net/coding-plan。模型对话测试用 https://taotoken.net/models，接入文档在 https://taotoken.net/doc，API Key 管理在 https://taotoken.net/api-keys。Claude Code 相关的接入说明在 https://taotoken.net/claudecode。
最后说一个实际经验：MCP 配置改完后，先用一个最简单的空间查询跑通，再逐步加 Tool。不要一上来就配五六个 GIS 服务，出问题时排查成本太高。一个服务、一个 Tool、一次查询，跑通了再复制。这样即使报错，你也能快速定位是 Key 问题、网络问题还是 GIS 服务本身的问题。
