---
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-cn/administration/accounts/roles/)。

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