PDF 工具箱 MCP 接入说明

English

PDF 工具箱是一个面向 Agent 的 MCP 文件处理服务，通过 Streamable HTTP 提供 PDF/图片转 Word、Excel、Markdown、PDF 拆分合并、图片转 PDF、文字水印和异步任务查询能力。支持 OAuth 和手动 API Key 两种授权方式。

1. 快速选择

场景	推荐方式
豆包正式接入	OAuth
MCP Client 支持浏览器授权	OAuth
MCP Client 不支持 OAuth，但支持自定义 Header	手动 API Key
curl、SDK、本地调试	手动 API Key

2. 固定配置

项目	值
MCP 服务地址	`https://api.tensormaster.com/pdf/mcp`
传输方式	Streamable HTTP
Resource	`https://api.tensormaster.com/pdf/mcp`
OAuth 注册方式	DCR（Dynamic Client Registration）
Scope	`mcp:tools offline_access`，使用 ASCII 空格分隔
客户端认证	`none`，Public Client + PKCE
Response Type	`code`
Grant Type	`authorization_code`、`refresh_token`
PKCE	必须使用 `S256`
Redirect URI	注册时传入，后续精确匹配，不支持通配符
OAuth Discovery	`https://miaodashi.com/.well-known/oauth-authorization-server`
Authorization Endpoint	`https://miaodashi.com/oauth/authorize`
Token Endpoint	`https://miaodashi.com/api/oauth/token`
Refresh Token Endpoint	留空，复用 Token Endpoint
DCR 注册地址	`https://miaodashi.com/api/oauth/register`

3. OAuth：豆包推荐方式

在豆包中按以下步骤操作：

在远程 MCP/Connector 中填写：
text
```
https://api.tensormaster.com/pdf/mcp
```
点击“去授权”
浏览器打开 MiaoDashi 授权页面；首次使用先注册，已有账号直接登录。
核对客户端名称、PDF 工具箱和权限范围，点击“同意授权”。
页面返回豆包后，确认状态显示“授权成功”或“已连接”。

DCR、state、PKCE、授权码兑换、Access Token 和 Refresh Token 均由豆包与 MiaoDashi 自动完成，用户无需手动复制授权码或 Token。Access Token 过期后，豆包使用 Refresh Token 自动续期。

Claude 接入步骤

将以下指令发送给 Claude：

text

帮我在设置里添加一个新的 MCP 连接器，地址是 https://api.tensormaster.com/pdf/mcp。添加后提醒我确认授权页面上的权限范围，再点同意。

然后按以下步骤完成授权：

退出 Claude，再重新进入 Claude。
输入 /mcp，选择 PDF 服务并进行授权。
确认授权成功后，即可使用 PDF 工具箱。

Codex（ChatGPT）接入步骤

打开 设置 → 插件 → 添加 → 添加 MCP 服务器。

填写：

text

名称：pdf
类型：流式 HTTP
URL：https://api.tensormaster.com/pdf/mcp

点击“保存”。
点击“进行身份验证”，注册或登录 MiaoDashi 网站，并在授权页面确认权限后点击“同意”。
返回设置页，确认“进行身份验证”按钮消失，即表示授权成功，可以使用 PDF 工具箱。

ChatGPT 的菜单名称可能因账号、工作区权限或版本略有差异；如果看不到添加 MCP 服务器入口，请先确认已启用相应的开发者模式或自定义连接器权限。

4. 手动 API Key：兼容方式

4.1 获取 API Key

打开 MiaoDashi API Keys，登录需要承担 PDF 费用的账号。
点击“创建 API Key”，填写名称，例如 pdf-mcp-local。
选择 PDF 工具需要的最小权限，至少需要文件处理/生成权限；按需设置过期时间。
创建成功后立即复制完整 Key。完整 Key 通常只显示一次，请保存到密码管理器或 MCP Client 安全存储。

不要使用网页内部 Key、OAuth Token、Device Flow Key 或其他服务的 Key。

4.2 配置 MCP Client

MCP Gateway 已启用手动 Key 兼容入口时，使用：

config.json

{
  "mcpServers": {
    "pdf-toolkit": {
      "type": "streamableHttp",
      "url": "https://api.tensormaster.com/pdf/mcp",
      "headers": {
        "Authorization": "Bearer md_api_<your_key>"
      }
    }
  }
}

也可以直接发送：

text

Authorization: Bearer md_api_<your_key>

不要把 API Key 放到 URL、Query、日志或聊天内容中。先调用 get_pdf_toolbox_capabilities 验证连接，再提交转换任务。

5. 工具列表

工具	主要参数	说明
`convert_file_to_word`	`file_url`, `idempotency_key`	PDF/图片转 DOCX
`convert_file_to_excel`	`file_url`, `idempotency_key`	PDF/图片转 XLSX
`convert_file_to_markdown`	`file_url`, `idempotency_key`	PDF/图片转 Markdown
`split_pdf`	`file_url`, `pages_per_file`, `idempotency_key`	拆分 PDF，结果通常为 ZIP
`merge_pdfs`	`file_urls`, `size`, `idempotency_key`	按数组顺序合并 PDF
`images_to_pdf`	`image_urls`, `scale`, `idempotency_key`	图片生成 PDF
`add_pdf_watermark`	`file_url`, 水印参数, `idempotency_key`	添加文字水印
`get_pdf_task`	`task_id`	查询状态、结果 URL、错误和积分
`list_pdf_tasks`	`cursor`, `limit`	查询当前用户的任务列表
`get_pdf_toolbox_capabilities`	无	查询格式、数量、大小和服务限制；无副作用

参数和任务规则

MCP 请求使用 JSON-RPC，不接收 multipart/form-data。
用户附件必须映射为临时 HTTPS URL：单文件使用 file_url，多文件使用 file_urls 或 image_urls。
split_pdf.pages_per_file 为 1..50；merge_pdfs 支持 2～10 个文件；images_to_pdf 支持 1～10 张图片；scale 为 (0, 1]。
创建任务必须使用 idempotency_key；相同参数重试不会重复创建或扣费。
任务状态：queued → running → succeeded/failed。使用 get_pdf_task 轮询，不要重复创建任务。
任务只能由所属用户查询。

6. 常见错误

错误	处理方式
`401` / `AUTH_REQUIRED`	OAuth 重新授权；手动模式检查 Key、过期和撤销状态
`403` / `INSUFFICIENT_SCOPE`	补充正确权限或重新授权
`INVALID_INPUT`	按 `tools/list` 返回的 schema 修正参数
`UNSUPPORTED_FILE_TYPE` / `FILE_TOO_LARGE`	查询 capabilities，转换格式或压缩文件
`SOURCE_URL_FORBIDDEN`	使用可访问的 HTTPS 临时 URL，不携带凭据
`INSUFFICIENT_CREDITS`	充值或切换有额度的账号
`CONCURRENCY_LIMITED`	等待已有任务完成
`TASK_NOT_FOUND`	检查 task ID；不能访问其他用户任务
`UPSTREAM_UNAVAILABLE`	稍后使用相同 `idempotency_key` 重试

7. 安全要求

全部 MCP、OAuth、Token 和发现地址使用 HTTPS。
Access Token、Refresh Token 和 API Key 只能放在 Authorization Header。
不要记录完整凭据、内部 JWT、Supabase 密钥或签名下载 URL。
文件 URL 必须经过 HTTPS、大小、重定向、DNS/IP 和超时校验，防止 SSRF。
怀疑 API Key 泄露时，立即在 MiaoDashi API Keys 页面撤销并重新创建。