---
title: "API 與 MCP 接入"
description: "建立 API 金鑰、驗證 REST 和 MCP 連接，並理解權限、更新與錯誤語義。"
---

> Documentation Index
> Fetch the complete documentation index at: https://cdelivery.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# API 與 MCP 接入

REST API 和 MCP 使用同一個平台操作目錄和授權規則。以下地址都屬於你自己部署的實例，而不是官網。

## 建立憑證

1. 打開**帳戶 → MCP / API 金鑰**，填寫可識別用途的名稱。
2. 選擇角色上限，並按需設定未來的到期時間。
3. 建立後立即儲存金鑰，完整值只展示一次。
4. 為不同工具分別建立金鑰，停用工具時撤銷對應金鑰。

名稱為 1–64 個 UTF-8 位元組。金鑰角色不能高於建立時的有效角色；實際權限始終受所屬使用者當前角色限制。密碼修改不撤銷金鑰，刪除使用者會使其金鑰失效。

## 驗證 REST

將實例地址和金鑰放入本地環境變數，先執行唯讀請求：

```sh
curl --fail-with-body "$CDELIVERY_URL/api/me" \
  -H "Authorization: Bearer $CDELIVERY_API_KEY"
```

成功時應回傳當前帳戶資訊。實例的 `/scalar` 提供交互式 API 文件，以執行版本的 schema 查看字段、枚舉和操作要求。避免在共享終端記錄或腳本儲存庫中硬編碼金鑰。

更新操作通常採用 patch 語義：省略字段保持不變；支援清空的字段用 `null` 清空，其他字段拒絕 `null`。空 patch 合法。枚舉值區分大小寫，按 schema 使用，例如 `Reader`、`Operator`、`Admin`。

## 設定 MCP

在支援遠程 HTTP MCP 的用戶端中，填寫實例的 `/mcp` 地址，並設定：

```text
Authorization: Bearer YOUR_API_KEY
```

具體設定格式由用戶端決定。連線後先列出工具並呼叫唯讀操作，確認帳戶與權限正確，再執行寫入操作。

## 排障與撤銷

| 結果 | 檢查 |
| --- | --- |
| 401 | 金鑰缺失、錯誤、到期、已撤銷，或所屬使用者不可認證 |
| 403 | 使用者當前角色或金鑰上限不足 |
| 422 | 字段校驗、互斥條件、缺失憑證或版本要求 |
| 連接失敗 | 實例地址、TLS、代理和路徑是否正確 |
| MCP 看見工具但呼叫失敗 | 具體操作的授權、參數和業務前置條件 |

撤銷金鑰後重新請求，確認舊憑證無法繼續存取。角色規則見[角色與權限](/docs/zh-tw/administration/accounts/roles/)。

Source: https://cdelivery.dev/docs/zh-tw/guides/automation/api-mcp/index.mdx