> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/mcp-server-api.md).

# MCP 服务器 API

注册 MCP 服务器，使用静态请求头或 OAuth 将其连接，并以编程方式将它们附加到角色上。

以编程方式管理 MCP 服务器。Playground 的 MCP 选项卡中可用的一切，也都可以通过 HTTP 使用：注册服务器、测试连接、连接 OAuth 账户，以及将服务器附加到角色。

有关 MCP 服务器是什么以及角色如何使用它们，请参阅 MCP Servers。

典型流程：

1. 用以下内容探测端点 `/mcp/servers/test`
2. 使用以下内容注册它 `/mcp/servers/create`
3. 对于 OAuth 服务器： `/mcp/oauth/start`，在浏览器中打开返回的 URL，然后轮询 `/mcp/oauth/status`
4. 使用以下内容将其附加到角色： `/mcp/characters/attach`

## 约定

* **基础 URL：** `https://api.convai.com/mcp`
* 所有端点都使用 **POST** 并使用 JSON 请求体（`Content-Type: application/json`），包括读取操作。唯一的例外是 OAuth 浏览器回调，你永远不会直接调用它。
* **认证：** 将你的 API 密钥放在 `CONVAI-API-KEY` 请求头中。每个请求都限定在你的账户范围内：你只能查看和修改自己的服务器和角色。
* **错误** 返回一个带有适当状态码的 JSON 包装：

```json
{ "ERROR": "name: 必填字段" }
```

| 状态  | 含义                       |
| --- | ------------------------ |
| 400 | 请求体无效。消息会指出失败的字段。        |
| 401 | 缺少或无效的 API 密钥。           |
| 404 | 引用的服务器或角色不存在（或不属于你）。     |
| 429 | 超过速率限制（每个端点每分钟 100 次请求）。 |
| 500 | 内部错误。可安全重试。              |

## 服务器对象

```json
{
  "server_id": "15e08050-2952-4380-8dfa-41242edbbcfe",
  "name": "order-lookup",
  "description": "用于支持角色的订单状态工具",
  "url": "https://mcp.example.com/mcp",
  "transport": "streamable_http",
  "auth_type": "headers",
  "auth_headers": { "Authorization": "Bearer sk-..." },
  "header_names": ["Authorization"],
  "tools_allowlist": ["lookup_order", "cancel_order"],
  "timeout_s": 30,
  "result_max_chars": null,
  "enabled": true,
  "created_at": "2026-08-19T09:18:44.783437"
}
```

* `auth_type`: `headers` （静态请求头，默认值）或 `oauth` （见 [OAuth 连接](#oauth-connections)).
* `auth_headers` 包含已存储的请求头值，仅返回给拥有该账户的人。 `header_names` 与仅有名称的集合相同，仅为兼容性保留。OAuth 令牌 **绝不** 不会被任何端点返回。
* `tools_allowlist`: `null` = 服务器公开的所有工具；列表 = 仅这些工具； `[]` = 无工具。
* `timeout_s` / `result_max_chars`: `null` = 平台默认值（30 秒 / 4,000 个字符）。

## 服务器端点

### 列出服务器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/servers/list` ，请求体为 `{}`。返回你账户中的所有服务器，最新的排在最前。

```json
{ "servers": [ { ...server object... } ] }
```

### 创建服务器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/servers/create`

| 字段                 | 必填 | 约束                                               |
| ------------------ | -- | ------------------------------------------------ |
| `name`             | 是  | 1–120 个字符                                        |
| `url`              | 是  | HTTPS，≤ 2048 个字符，完整的 MCP 端点路径（通常以 `/mcp`)        |
| `描述`               | 否  | ≤ 2000 个字符                                       |
| `transport`        | 否  | `streamable_http` （默认）或 `sse`                    |
| `auth_type`        | 否  | `headers` （默认）或 `oauth`                          |
| `auth_headers`     | 否  | 由头名称 → 值组成的对象；最多 20 个头，名称最多 120 个字符，值最多 8192 个字符 |
| `tools_allowlist`  | 否  | 工具名称数组；最多 200 项，名称最多 128 个字符；所有工具则省略             |
| `timeout_s`        | 否  | 整数 1–300                                         |
| `result_max_chars` | 否  | 整数 100–100000                                    |

返回 `{ "server": { ... } }`。头值在静态存储时会加密。

### 更新服务器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/servers/update` ，请求体为 `{ "server_id": "...", ...要更改的字段 }`.

部分更新：未提供的字段保持不变。 `enabled: false` 会在所有地方禁用该服务器，但不会解除附加。返回已更新的 `{ "server": { ... } }`.

**请求头保留标记：** 在……内部 `auth_headers`，空字符串值表示“保留此请求头的已存储值”。要移除某个请求头，请发送 `auth_headers` 但不包含它；要清空所有请求头，请发送 `auth_headers: null`.

设置 `auth_type` 为 `headers` 在 OAuth 连接的服务器上执行会断开连接：已存储的令牌会与提供商一起撤销并删除。

### 删除服务器

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/servers/delete` ，请求体为 `{ "server_id": "..." }`。移除服务器及其所有角色附加项。对于 OAuth 服务器，已存储的令牌会与提供商一起撤销并删除。返回 `{ "status": "success" }`.

### 测试连接

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/servers/test` 有两种互斥模式：

* **创建前探测：** `{ "url": "...", "transport"?, "auth_headers"? }`
* **已保存的服务器：** `{ "server_id": "..." }`。使用已存储的 URL、transport 和凭据。OAuth 服务器会使用已连接账户的实时令牌进行探测。

返回发现的工具，或诊断信息：

```json
{ "ok": true, "tools": [ { "name": "lookup_order", "description": "..." } ] }
{ "ok": false, "error": "在 initialize 时出现 HTTP 401（检查 URL 和认证）" }
```

连接失败会报告在 `ok: false` HTTP 200 的响应体中；非 200 状态表示请求本身失败，而不是被探测的服务器。

## OAuth 连接

具有 `auth_type: "oauth"` 通过连接账户而不是存储请求头值来进行认证。该流程只有一个浏览器步骤，即账户所有者在提供商处登录；其余都是 API 调用：

1. 使用以下内容创建服务器 `auth_type: "oauth"` 并且不传 `auth_headers`.
2. 调用 `/mcp/oauth/start`。它会返回一个 `authorize_url`.
3. 打开 `authorize_url` ，在浏览器中打开，登录并批准所请求的访问。提供商会重定向回 Convai，连接会在服务器端完成。
4. 轮询 `/mcp/oauth/status` 直到 `status` 是 `已连接`.

Convai 会自动与大多数提供商注册。令牌会被加密存储并自动刷新；任何端点都不会返回它们。

### 开始连接

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/oauth/start`

| 字段              | 必填 | 备注                            |
| --------------- | -- | ----------------------------- |
| `server_id`     | 是  | 必须是 `streamable_http` 服务器。    |
| `client_id`     | 否  | 仅适用于不允许自动注册的提供商；见下文。          |
| `client_secret` | 否  | 同上；公有客户端可省略。                  |
| `scopes`        | 否  | 以空格分隔的 scope 字符串。省略则使用提供商默认值。 |

```json
{ "ok": true, "authorize_url": "https://mcp.notion.com/authorize?client_id=..." }
```

该 URL 仅可使用一次，并将在几分钟后过期；请再次调用 `/mcp/oauth/start` 以获取新的 URL。流程失败（例如提供商拒绝自动注册）会以以下形式返回 `{ "ok": false, "error": "..." }` 并返回 HTTP 200。

**需要已注册应用的提供方** （Google 和大多数企业身份系统）会拒绝自动注册； `start` 返回一个说明该情况的错误。请在提供商控制台中创建 OAuth 应用，注册 `https://api.convai.com/mcp/oauth/callback` 作为其重定向 URL，并调用 `start` 再次使用该应用的 `client_id` （以及 `client_secret`，如果已发放）。

### 检查连接状态

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/oauth/status` ，请求体为 `{ "server_id": "..." }`.

```json
{ "status": "已连接", "scope": "默认" }
```

| `status` | 含义                                   |
| -------- | ------------------------------------ |
| `未连接`    | 没有连接。使用 `/mcp/oauth/start`.          |
| `待处理`    | 连接已启动，但浏览器步骤尚未完成。                    |
| `已连接`    | 已连接；服务器的工具可用。 `scope` 是提供商授予的内容。     |
| `需要重新授权` | 提供商已使该授权失效。运行 `/mcp/oauth/start` 状态。 |

### 断开连接

<mark style="color:绿色;">`POST`</mark> `https://api.convai.com/mcp/oauth/disconnect` ，请求体为 `{ "server_id": "..." }`。在提供商处撤销该授权（尽力而为）并删除已存储的令牌。服务器配置保留，因此你之后可以重新连接。返回 `{ "status": "success" }`.

## 角色附加项

* <mark style="color:绿色;">`POST`</mark> `/mcp/characters/list` ，请求体为 `{ "character_id": "..." }` 返回 `{ "server_ids": ["..."] }`
* <mark style="color:绿色;">`POST`</mark> `/mcp/characters/attach` ，请求体为 `{ "character_id": "...", "server_id": "..." }` 返回 `{ "status": "success" }`。两者都必须属于你的账户。幂等。
* <mark style="color:绿色;">`POST`</mark> `/mcp/characters/detach` ，请求体为 `{ "character_id": "...", "server_id": "..." }` 返回 `{ "status": "success" }`。幂等。

附加的工具会在该角色的下一次对话会话中生效。

## 示例：请求头认证服务器

```bash
# 先探测，再注册并附加
curl -s https://api.convai.com/mcp/servers/test \\
  -H "CONVAI-API-KEY: $CONVAI_API_KEY" -H "Content-Type: application/json" \\
  -d '{"url": "https://mcp.example.com/mcp"}'

curl -s https://api.convai.com/mcp/servers/create \\
  -H "CONVAI-API-KEY: $CONVAI_API_KEY" -H "Content-Type: application/json" \\
  -d '{"name": "order-lookup", "url": "https://mcp.example.com/mcp",
       "auth_headers": {"Authorization": "Bearer sk-..."}}'

curl -s https://api.convai.com/mcp/characters/attach \\
  -H "CONVAI-API-KEY: $CONVAI_API_KEY" -H "Content-Type: application/json" \\
  -d '{"character_id": "<character_id>", "server_id": "<server_id from create>"}'
```

## 示例：OAuth 服务器

```bash
# 注册、启动连接、打开 URL、轮询直到已连接
curl -s https://api.convai.com/mcp/servers/create \\
  -H "CONVAI-API-KEY: $CONVAI_API_KEY" -H "Content-Type: application/json" \\
  -d '{"name": "notion", "url": "https://mcp.notion.com/mcp", "auth_type": "oauth"}'

curl -s https://api.convai.com/mcp/oauth/start \\
  -H "CONVAI-API-KEY: $CONVAI_API_KEY" -H "Content-Type: application/json" \\
  -d '{"server_id": "<server_id>"}'
# -> { "ok": true, "authorize_url": "https://..." }   在浏览器中打开此 URL

curl -s https://api.convai.com/mcp/oauth/status \\
  -H "CONVAI-API-KEY: $CONVAI_API_KEY" -H "Content-Type: application/json" \\
  -d '{"server_id": "<server_id>"}'
# -> { "status": "已连接", "scope": "默认" }
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/character-crafting-apis/mcp-server-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.