MCP 接入指南：获取 Key 与基础配置

六步完成 MCP 接入，从申请 Key 到在对话中生成第一条短链。

1. 准备工作

开始配置之前，请先确认以下三件事：

• 申请 MCP Key：联系管理员或在个人中心开通 MCP 权限，获取 secret-key
• 区分两种凭证：MCP Key 与 API Token 相互独立——API Token 用于调用 REST 接口，MCP Key 用于 AI 客户端鉴权，请勿混用
• 确认客户端能力：客户端需支持 streamable-http 传输的远程 MCP Server（Remote MCP Server）

2. 基础配置 JSON

绝大多数客户端都通过一段包含 mcpServers 字段的 JSON 完成配置。小南短链 MCP 的标准配置结构如下：

{
  "mcpServers": {
    "xnanlink": {
      "type": "streamable-http",
      "url": "https://mcp.xnanlink.com/link/mcp",
      "headers": {
        "secret-key": "YOUR_MCP_KEY"
      }
    }
  }
}

各字段的含义与要求：

3. 配置步骤（六步）

3.1 申请 MCP Key

联系管理员或在个人中心开通 MCP 权限，获取 secret-key。再次提醒：MCP Key 与 API Token 相互独立，此处需要的是 MCP Key。

3.2 选择支持 MCP 的客户端

推荐使用 Cherry Studio、Claude Desktop、Cursor、Windsurf。使用前请确认客户端版本支持 streamable-http 远程 MCP Server。

3.3 打开 MCP 配置文件

不同客户端的配置文件位置不同，通常是一个包含 mcpServers 字段的 JSON 文件。例如 Claude Desktop 为 claude_desktop_config.json，Cursor 为 ~/.cursor/mcp.json。图形化客户端（如 Cherry Studio）则可直接在设置面板中填写。

3.4 粘贴配置并替换 Key

将上文「基础配置 JSON」合并进客户端配置文件（注意不要覆盖已有的其它 MCP 服务），并把 secret-key 的值替换为你自己的 MCP Key。

3.5 重启客户端 / 刷新 MCP

保存配置后重启客户端，或在 MCP 设置面板点击刷新。看到 xnanlink 服务状态变为「已连接」即配置成功。

3.6 在对话中使用

直接用自然语言提问即可，例如：「帮我生成一个 example.com 的短链」。模型会自动调用对应工具并把结果返回到对话中。

4. 验证连接是否成功

进入客户端的 MCP 设置面板，检查以下两点：

• 服务状态：xnanlink 显示为「已连接」（部分客户端显示为绿色圆点）
• 工具列表：能看到 create_link、search_link_list 等 10+ 个工具

如果连接失败，请按以下顺序排查：

• Key 错误：检查 secret-key 是否完整复制、有无多余空格或换行
• 客户端版本过低：旧版本可能不支持 streamable-http 传输，请升级到最新版本
• 网络问题：确认当前网络能正常访问 https://mcp.xnanlink.com/link/mcp，代理环境下注意放行该域名

5. 安全建议

• 妥善保管 MCP Key：不要把包含 Key 的配置文件提交到代码仓库，也不要在截图、群聊中公开分享。项目级配置文件（如 .cursor/mcp.json）建议加入 .gitignore
• 泄露后及时处理：一旦怀疑 Key 泄露，请立即联系管理员重置，旧 Key 失效后更新各设备上的配置即可

6. 常见问题

7. 下一步

完成基础接入后，可以查看各客户端的详细配置说明：

• MCP 客户端配置参考——Claude Desktop、Cursor、Cherry Studio、Windsurf 等客户端的逐步配置指引