📖 MCP & API
🎯 入门
⏱ 5 分钟
MCP & API 常见问题
汇总 API 调用与 MCP 接入中最常遇到的问题与解决方法。
1. 凭证与鉴权
Q
MCP Key 和 API Token 是什么关系？
两者相互独立。API Token 用于调用 REST 接口（请求头
Token），MCP Key 用于在支持 MCP 协议的 AI 客户端中鉴权（请求头 secret-key）。两者分别申请、分别重置，开通 MCP Key 后调用额度与当前套餐保持一致，无需额外购买。
Q
Token / Key 泄露了怎么办？
立即在个人中心重置对应凭证，或联系管理员协助处理。重置后旧凭证立刻失效，请将新凭证更新到你的程序或 MCP 客户端配置中。由于 API Token 与 MCP Key 相互独立，重置其中一个不会影响另一个的正常使用。平时请避免将凭证提交到代码仓库或在截图中暴露。
Q
鉴权失败（401）常见原因排查
常见原因包括：凭证填错或包含多余空格；请求头名称写错（API 应为
Token，MCP 应为 secret-key）；用 API Token 去连 MCP 或用 MCP Key 去调 API，两者不能混用；凭证已被重置但客户端仍在使用旧值。逐项核对后重试即可。
2. 额度与套餐
Q
MCP 调用会消耗我的套餐额度吗？
会。MCP 调用与 API 调用共享同一套套餐额度。免费体验版每日有限额调用（100 次 / 天），专业版及以上调用次数无限制，且支持访问统计与专属技术支持。
Q
免费版能用哪些 MCP 工具？
免费体验版开放 5 个常用工具，可满足日常生成与查询短链的轻度需求，但不含批量工具和访问统计工具。专业版及以上开放全部 10+ 个工具，包括访问记录查询等统计能力。
Q
超出额度后调用会发生什么？
免费版超出每日限额后，当日后续调用会被拒绝并返回相应的错误提示，次日额度自动恢复。如经常触达限额，建议升级到专业版，调用次数无限制。
3. MCP 连接问题
Q
哪些客户端可以使用短链 MCP？
凡支持 Remote MCP Server 且支持 Streamable HTTP 传输方式的客户端均可使用，包括 Cherry Studio、Claude Desktop、Cursor、Windsurf 以及 VS Code 的 MCP 扩展等。接入地址统一为
https://mcp.xnanlink.com/link/mcp。
Q
配置完成后如何验证是否连接成功？
保存配置后重启客户端或在 MCP 设置面板点击刷新，看到
xnanlink 服务状态变为「已连接」即配置成功。随后可直接在对话中用自然语言调用短链工具，例如「帮我生成一个 example.com 的短链」。
Q
客户端不支持自定义 Header 怎么办？
部分客户端不支持自定义请求头，可联系管理员协助开通 URL Token 模式，将
secret-key 作为 URL 参数携带，兼容性更强。
Q
服务显示已连接但工具调用失败？
先确认
secret-key 是否有效（是否被重置过、是否有多余空格）；再确认套餐额度是否已用尽，免费版每日限额用完后调用会失败；最后确认调用的工具是否在你的套餐开放范围内（免费版仅 5 个常用工具）。如仍无法解决，请联系管理员协助排查。
4. API 调用问题
Q
统一响应结构怎么判断成功？
所有接口返回统一的 JSON 结构，包含
code、message、data、success 四个字段。code=OK 且 success=true 表示成功，业务数据在 data 字段中；失败时 message 会给出具体原因。
Q
创建短链时提示访问码重复怎么办？
自定义访问码在同一域名下必须唯一。建议在创建前先调用
GET /api/link/check-visit-code 检查后缀是否已被使用（data 为 false 表示可用），再发起创建；或者不传 visitCode，由系统随机生成不重复的访问码。
Q
批量导入失败的数据在哪里下载？
调用
POST /api/link/import/list 查询导入历史，每条任务记录中包含总数量、成功数量、失败数量，以及 failDataOssPath 字段——即失败数据文件的下载路径，下载后修正数据即可重新导入。
Q
接口有频率限制吗？
限制主要取决于套餐：免费体验版每日 100 次调用，专业版及以上调用次数无限制；企业版还提供专属并发通道与 SLA 保障。如有大规模高并发需求，建议使用批量接口（如批量导入、批量修改状态）减少请求次数，或联系管理员评估企业版方案。
5. 能力与场景
Q
可以用自然语言做哪些操作？
生成短链、快捷生成短链、更新目标地址或配置、启用/禁用短链、删除短链、查询短链详情、分页查询短链列表、查询访问记录、检查后缀是否重复、获取可用域名列表等，均可在 AI 客户端中通过自然语言触发对应工具完成。
Q
MCP 里没有的功能（如批量导入）怎么办？
使用 API。MCP 工具是 API 的子集，Excel/JSON 批量导入、批量修改域名前缀、导入历史管理等能力目前仅通过 API 提供（接入地址
https://open.xnanlink.com），可参考 API 接口文档中的批量导入相关接口。
Q
API 和 MCP 操作的是同一份数据吗？
是的。两种方式操作的都是同一账号下的同一份短链数据：通过 API 创建的短链可以在 MCP 中查询和修改，通过 MCP 生成的短链也会出现在 API 查询结果和后台管理界面中。
6. 相关阅读
如果以上问题没有覆盖你的情况，可以继续阅读以下文章：
- 开放能力总览：API 与 MCP —— 了解两种开放能力的整体结构
- MCP 与 API 的区别：如何选择？ —— 从多个维度对比两种接入方式
- API 快速入门 / MCP 接入指南 —— 按步骤完成首次接入
!
小贴士
遇到文档未覆盖的问题，可随时联系管理员或技术支持。反馈时附上请求示例（注意隐去 Token / Key）与返回的错误信息，能大幅加快定位速度。