# 透過 MCP 連接 Agent

[HTML](https://pdfcraft.ai/zh-Hant/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-Hant/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-Hant/docs/api/overview/)。