📖 MCP & API
🎯 入门
⏱ 5 分钟
什么是 MCP？用自然语言管理短链
通过 MCP 协议把短链能力接入 Claude、Cursor 等 AI 客户端，对话即操作。
1. MCP 是什么？
MCP（Model Context Protocol，模型上下文协议）是一种连接 AI 模型与外部服务的开放协议。它的核心理念是：把平台的能力以「工具调用」的方式提供给 AI 模型——模型理解你的自然语言意图后，自动选择并调用合适的工具，替你完成实际操作。
小南短链通过 MCP 协议，把短链管理能力接入 Claude、Cursor、Cherry Studio、Windsurf 等支持 MCP 的 AI 客户端。配置完成后，你不需要写一行代码，在对话框里说出需求即可完成短链的创建、查询与管理。
与传统 API 的直观对比：
| 对比维度 | 传统 API | MCP |
|---|---|---|
| 使用方式 | 写代码调接口，拼装参数、解析响应 | 自然语言下指令，AI 自动调用工具 |
| 技术门槛 | 需要开发能力，适合系统集成 | 零代码，配置一次即可对话使用 |
| 典型场景 | 业务系统自动化、批量任务 | 日常运营操作、临时查询与管理 |
2. 短链 MCP 服务概览
小南短链 MCP 是一个 Remote MCP Server（远程 MCP 服务），无需在本地安装任何程序，客户端直接通过 HTTP 连接即可使用。三个关键连接信息如下：
| 配置项 | 值 | 说明 |
|---|---|---|
| 服务地址 | https://mcp.xnanlink.com/link/mcp |
MCP 服务的固定 URL |
| 传输方式 | streamable-http |
Remote MCP Server 的流式 HTTP 传输 |
| 鉴权方式 | 请求头 secret-key |
值为管理员发放的 MCP Key |
3. 能用自然语言做什么？
连接成功后，直接在对话中描述需求，模型会自动匹配并调用对应的工具。例如：
- 「帮我生成一个 example.com 的短链」→ 调用
create_link - 「查一下 abc123 这条短链的访问记录」→ 调用
query_visit_log - 「把这条短链停用」→ 调用
update_link_status
目前小南短链 MCP 提供 10+ 个工具，覆盖短链管理的完整链路：创建、快捷创建、更新、启停、删除、详情查询、后缀校验、列表查询、访问记录与域名列表。
4. 工具与 API 的对应关系
每个 MCP 工具背后都对应一个 REST API 接口，工具的入参、能力边界与对应接口一致。例如 create_link 对应 POST /api/link/create。完整对照表如下：
| MCP 工具 | 功能 | 对应 API |
|---|---|---|
create_link |
生成一条新的短链 | POST /api/link/create |
quick_create_link |
快捷方式生成短链 | POST /api/link/quick-create |
update_link |
更新短链目标地址或配置 | POST /api/link/update |
update_link_status |
启用/禁用短链 | POST /api/link/update-status |
delete_link |
删除指定短链 | POST /api/link/delete |
link_detail |
查询短链详情 | GET /api/link/detail |
check_visit_code |
检查短链后缀是否重复 | GET /api/link/check-visit-code |
search_link_list |
分页查询短链列表 | POST /api/link/list |
query_visit_log |
查询短链访问记录 | POST /api/chart/visit-log |
list_domains |
获取可用域名列表 | GET /api/link/domain/list |
5. 支持的客户端
凡支持 Remote MCP Server 且支持 Streamable HTTP 传输方式的客户端均可接入小南短链 MCP，常见的包括：
- Cherry Studio：图形化配置，在设置面板中添加 MCP 服务器即可
- Claude Desktop：编辑
claude_desktop_config.json配置文件 - Cursor：编辑
~/.cursor/mcp.json或项目级.cursor/mcp.json - Windsurf：设置 → Cascade → MCP Servers 中编辑配置
- VS Code MCP 扩展及其它支持 Streamable HTTP 的 MCP 客户端
!
小贴士
接入前请确认客户端版本较新且支持 streamable-http 传输的 Remote MCP Server。部分旧版本客户端仅支持本地 stdio 方式，无法直接连接远程服务。
6. 套餐与额度
MCP 调用与 API 调用共享同一套套餐额度，开通 MCP Key 不需要额外购买额度。各套餐的差异如下：
| 套餐 | 工具范围 | 调用额度 | 支持服务 |
|---|---|---|---|
| 免费体验 | 5 个常用工具 | 100 次调用 / 天 | 社区支持 |
| 专业版 | 全部 10+ 个工具（含访问统计） | 调用次数无限制 | 邮件技术支持 |
| 企业版 | 全部工具，可定制工具与字段 | 专属并发通道 | SLA 保障、专属技术支持 |
7. 常见问题
Q
MCP Key 和 API Token 是什么关系？
两者相互独立。API Token 用于调用 REST 接口，MCP Key 用于在支持 MCP 协议的 AI 客户端中鉴权。开通 MCP Key 后，调用额度与你当前套餐保持一致，无需额外购买。
Q
使用 MCP 需要会写代码吗？
不需要。MCP 的初始配置只需在客户端中粘贴一段 JSON（或在图形界面填写地址和 Key），之后所有操作都通过自然语言对话完成，生成短链、查询访问记录、启停短链等都不需要任何编程知识。
Q
MCP 调用安全吗？
服务通过 HTTPS 加密传输，所有请求都需要携带
secret-key 鉴权，只有持有有效 MCP Key 的客户端才能调用你账号下的工具。请妥善保管 Key，避免提交到代码仓库或公开分享；若发生泄露，请联系管理员重置。
8. 下一步
了解了 MCP 的能力后，几分钟就可以完成接入：
- MCP 接入指南：获取 Key 与基础配置——六步完成接入，从申请 Key 到生成第一条短链
- MCP 客户端配置参考——Claude Desktop、Cursor、Cherry Studio 等客户端的详细配置步骤