DocUnwrap 文档
开发文档

MCP 接入

一个 URL 把 DocUnwrap 的文档解析能力接进 Claude / Cursor / VS Code / ZCode 等 AI 客户端。

MCP(Model Context Protocol)让 AI 客户端直接调用 DocUnwrap:配一次端点,之后在对话里 丢一个 PDF 链接,agent 自己提交解析、等待完成、取回全文 —— 零代码接入。

下文以 https://docunwrap.com/mcp 为例,请把域名替换为你实际访问本站的域名 (本地开发即 http://localhost:3000/mcp)。

端点与鉴权

  • 端点:https://docunwrap.com/mcp(Streamable HTTP,无状态,单端点)
  • 鉴权:API Key(获取方式),三种等价形态:
Authorization: Bearer docunwrap_live_xxxx   # 请求头(推荐,多数客户端用这个)
x-api-key: docunwrap_live_xxxx              # 请求头(等价)
https://docunwrap.com/mcp?key=docunwrap_live_xxxx  # URL 查询参数(只填得了 URL 的客户端用)

各客户端接入

Cursor

把下面一行粘贴进终端(先把 YOUR_KEY 换成真实 key),输出的链接在浏览器打开即完成安装:

printf '%s' '{"url":"https://docunwrap.com/mcp","headers":{"Authorization":"Bearer docunwrap_live_YOUR_KEY"}}' | base64
# → 拼成 https://cursor.com/install-mcp?name=docunwrap&config=<上面的输出>

或手动编辑 ~/.cursor/mcp.json(项目级则放 .cursor/mcp.json):

{
  "mcpServers": {
    "docunwrap": {
      "url": "https://docunwrap.com/mcp",
      "headers": { "Authorization": "Bearer docunwrap_live_YOUR_KEY" }
    }
  }
}

VS Code(Copilot Chat)

浏览器打开深链(先把 URL 里的 docunwrap_live_YOUR_KEY 换成真实 key):

vscode://mcp/install?%7B%22name%22%3A%22docunwrap%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A//docunwrap.com/mcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20docunwrap_live_YOUR_KEY%22%7D%7D

或手动编辑 mcp.json(命令面板 → MCP: Add Server,或直接编辑用户级配置):

{
  "servers": {
    "docunwrap": {
      "type": "http",
      "url": "https://docunwrap.com/mcp",
      "headers": { "Authorization": "Bearer docunwrap_live_YOUR_KEY" }
    }
  }
}

Claude Code(CLI)

claude mcp add --transport http docunwrap https://docunwrap.com/mcp \
  --header "Authorization: Bearer docunwrap_live_YOUR_KEY"

claude.ai(网页版自定义连接器)

Settings → Connectors → Add custom connector,URL 填(key 直接带在查询参数里, 因为连接器表单只收 URL):

https://docunwrap.com/mcp?key=docunwrap_live_YOUR_KEY

其他任意 MCP 客户端(ZCode / Windsurf 等)

通用参数就三样:端点 URL https://docunwrap.com/mcp、请求头 Authorization: Bearer <key>、协议 Streamable HTTP(无状态,无需会话)。

工具清单

服务端精选了 4 个工具(学 Stripe MCP 的小集合打法,不裸露 API 全集):

工具作用关键参数
parse_document提交解析并默认等待完成,直接返回结果内容file_url(必填)、output_format、model、wait、max_wait_seconds(默认 60,上限 120)
get_task查任务状态与页级进度task_id
get_task_result取已完成任务的结果全文,支持分页task_id、offset、max_length(默认 30000,上限 100000 字符)
list_tasks列出最近的解析任务limit(默认 10,上限 50)

parse_document 的等待语义:

  • 文本层 PDF(数字原生)通常数秒完成,一次调用直接拿到全文(超长结果截断到 20000 字符预览,truncated: true 时用 get_task_result 分页取全量);
  • 扫描件耗时更长,超过 max_wait_seconds 仍未完成会返回当前进度与 task_id,agent 稍后用 get_task 轮询即可。

错误(余额不足、并发超限、参数非法等)以 isError: true 的工具结果返回, error.code 与 REST API 错误码同构。

计费与限额

与 REST 完全一致:按实际页数 × 模型单价在任务完成时扣减(见 接入总览)。等待轮询发生在服务端 —— 一次 parse_document 调用只消耗 1 次请求配额(每 key 60 次/分钟),无论等多久。

用 Inspector 调试

官方 MCP Inspector (浏览器客户端)可直接调试本端点,CORS 已放开:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP
# URL: https://docunwrap.com/mcp
# Authorization: Bearer docunwrap_live_YOUR_KEY

On this page