# 通过 MCP 连接 Agent

[HTML](https://pdfcraft.ai/zh-CN/docs/getting-started/mcp/)
[Site index](https://pdfcraft.ai/llms.txt)

让 AI Agent 使用 PDFCraft 转换和翻译 PDF、EPUB 文件。


将 PDFCraft 接入支持远程 MCP 的 AI Agent，就能让它把 PDF 转为 Markdown 或 EPUB、翻译 PDF 和 EPUB，还能查询余额、估算费用和获取转换结果。

## 配置连接

1. 前往 [OOMOL Console](https://console.oomol.com/api-key)，创建自己的 API Key。
2. 在 Agent 设置中添加远程 MCP 服务，地址填入 `https://api.pdfcraft.ai/v1/mcp`，传输方式选择 Streamable HTTP。
3. 添加请求头 `Authorization: Bearer YOUR_API_KEY`，将 `YOUR_API_KEY` 替换为自己的密钥。

以下 JSON 展示需要配置的连接信息。不同客户端的配置字段可能不同，请将这些值填入对应的地址和 HTTP 请求头设置：

```json
{
  "url": "https://api.pdfcraft.ai/v1/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY"
  }
}
```

请将密钥保存在客户端的安全设置中，不要粘贴到对话里，也不要放进文件链接。转换会消耗 PDFCraft 点数，可前往[充值页](https://pdfcraft.ai/zh-CN/recharge/)充值。

## 确认客户端兼容性

服务使用 Streamable HTTP，MCP 协议版本为 `2026-07-28`。客户端需要支持该版本，并允许自行设置 Bearer 鉴权请求头。不支持 2025 版本的旧初始化和会话流程。

目前没有交互式 OAuth 登录。若客户端强制要求 OAuth，且不能配置 Bearer API Key，就无法直接连接。

## 开始第一次转换

连接后，Agent 可以发现工具并读取使用说明。先让它调用 `get_capabilities`，了解支持的格式、语言和使用流程。例如，你可以说：

> 把这份 PDF 转成 EPUB，开始前先查一下余额，估算费用。

Agent 需要能读取并上传文件的实际内容；仅提供本机路径，远程服务无法读取。随后它可以创建任务、上传文件、启动处理、查询进度并获取下载链接。保留任务 UUID，方便之后继续。

默认下载完整版。如果因为欠费无法下载，充值后为同一个任务重新获取链接即可。只有明确请求且存在可用版本时，才会返回不完整的文件。

如需在自己的程序中直接调用接口，请参阅 [REST API 参考](https://pdfcraft.ai/zh-CN/docs/api/overview/)。