---
title: 连接AI客户端 (MCP)
description: 将Claude Code、Codex CLI、Gemini CLI、Cursor、Claude Desktop、claude.ai、ChatGPT或OpenAI SDK连接到面板的管理员MCP端点，并使用完整的工具列表。
url: https://nexcmp.com/zh-cn/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 连接AI客户端 (MCP) {#connect-an-ai-client-mcp}

> **管理后台位置**：System › Settings › API & AI agents（`/agent/keys`），**Connect an AI**标签页显示了每个客户端的端点URL以及随时可复制的代码片段，其中已填入您刚刚创建的密钥。

## 功能说明 {#what-it-does}

**Model Context Protocol (MCP)**允许AI客户端调用工具。您的面板在`https://cloud.example.com/mcp/admin`提供管理员MCP端点。将您自己的AI工具连接到它，并用日常语言提问：“还有什么需要设置的？”、“添加我的Proxmox cluster”、“创建利润率为40%的套餐”。客户端将调用下方的管理员工具；面板会检查权限范围，在进行任何高风险操作前向您确认，并记录每一次调用。

::: info 两个MCP端点
`/mcp`是**客户**端点（客户API密钥，`vk_`；参见[MCP server](https://nexcmp.com/zh-cn/docs/developers/mcp/)）。`/mcp/admin`是此处描述的**管理员**端点（管理员密钥`ak_`或OAuth）。这两者永不混用：管理员工具在`/mcp`上不可见，且`/mcp/admin`仅接受管理员密钥。
:::

## 前提条件 {#requirements}

| 项目 | 要求 |
|---|---|
| 端点 | 面板自己域名上的`https://cloud.example.com/mcp/admin`。请从**Connect an AI**标签页复制准确的URL。同一页面还列出了用于在服务器本身上运行的工具的本地URL（`http://127.0.0.1:<port>/mcp/admin`）。 |
| 凭据 | 具有所需权限范围的[admin API key](https://nexcmp.com/zh-cn/docs/configure-with-ai/admin-api-keys/)（`ak_...`），**或者**用于Web连接器的OAuth登录（[OAuth connectors](https://nexcmp.com/zh-cn/docs/configure-with-ai/oauth-connectors/)）。 |
| 客户端 | 支持**Streamable HTTP**传输协议以及自定义`Authorization`请求头的任何MCP客户端。支持协议版本2025-11-25、2025-06-18和2025-03-26。 |
| 网络 | 如果您在面板前放置了自己的反向代理，它必须转发`/mcp/admin`。由于Web连接器（claude.ai、ChatGPT）从供应商的服务器进行连接，因此该URL必须可以从公网访问。 |

## 准备基础设施 {#prepare-the-infrastructure}

服务器上无需安装任何软件。如果您通过IP限制密钥，请确保客户端连接的地址在允许范围内。请先测试连通性：

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

返回`401`且带有`WWW-Authenticate: Bearer ... resource_metadata=...`请求头的响应意味着端点正在运行且需要凭据。

## 在NexCMP中连接 {#connect-in-nexcmp}

1. 创建密钥：**System › Settings › API & AI agents › API keys › New key**。初次尝试时仅使用`admin:read`；在需要时再添加写入权限范围。参见[Admin API keys](https://nexcmp.com/zh-cn/docs/configure-with-ai/admin-api-keys/)。
2. 打开**Connect an AI**标签页。“密钥已创建”对话框刚弹出时，下方的每个代码片段就已经包含了您的真实密钥。否则它将显示占位符`ak_YOUR_KEY`。
3. 复制适用于您的客户端的代码片段，并按照下文所述运行或粘贴它。

![带有MCP URL的Connect an AI标签页，每个客户端对应一个带复制按钮的卡片](https://nexcmp.com/zh-cn/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"
```

然后启动`claude`并询问“列出nexcmp中的工具”或“还有什么需要设置的？”。

于30/10/2026在Claude Code 2.1上验证：`claude mcp add --transport http …`将服务器写入项目（添加`-s project`以将其保留在项目的`.mcp.json`中——Claude Code首次运行会要求您批准项目服务器）。对于脚本，`claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"`运行是不需要批准提示，并允许Claude仅使用面板的工具。

### Claude Desktop {#claude-desktop}

需要Node.js 18或更高版本。将此内容添加到`claude_desktop_config.json`（它使用`mcp-remote`桥接）并重启Claude Desktop：

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

如果您的系统在请求头参数中处理空格时出错，请改用环境变量传入整个值，格式与客户端点完全相同：通过 `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` 配合 `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`。

### claude.ai (自定义连接器) {#claude-ai-custom-connector}

无需密钥：它通过OAuth登录。在claude.ai中打开连接器设置，添加自定义连接器，粘贴`https://cloud.example.com/mcp/admin`，然后使用您的NexCMP管理员账户登录并在授权界面上选择权限。详情：[OAuth connectors](https://nexcmp.com/zh-cn/docs/configure-with-ai/oauth-connectors/)。

### ChatGPT (开发者模式) {#chatgpt-developer-mode}

无需密钥。在ChatGPT中开启开发者模式，添加一个URL为`https://cloud.example.com/mcp/admin`的MCP连接器，选择OAuth并使用您的NexCMP管理员账户登录。详情：[OAuth connectors](https://nexcmp.com/zh-cn/docs/configure-with-ai/oauth-connectors/)。

### Codex CLI {#codex-cli}

添加到 `~/.codex/config.toml`：

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

然后在启动 Codex 的 shell 中导出密钥：

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip 非交互式 `codex exec`
在`codex exec`（脚本、CI）中，Codex在调用工具前不会询问，并且会跳过修改数据的工具。添加`default_tools_approval_mode = "approve"`至`[mcp_servers.nexcmp]`下以允许其调用工具；对于资金、安全和删除操作，面板仍会返回预览并请求确认。于30/10/2026通过Codex CLI 0.166验证。
:::

### Gemini CLI {#gemini-cli}

添加到 `~/.gemini/settings.json`：

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI会在其不信任的文件夹中关闭MCP servers。请在您信任的文件夹中启动它（或在系统询问时信任该文件夹），然后使用`gemini mcp list`进行检查——它将显示`nexcmp … Connected`。您可以使用`"Authorization": "Bearer $NEXCMP_KEY"`将密钥保留在文件之外。已于30/10/2026通过Gemini CLI 0.66验证。

### Cursor {#cursor}

添加到 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）：

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip 将密钥保存在配置文件之外
在客户端支持的情况下，从环境变量读取密钥，而不是将其写入文件中：Codex 默认会这样做（`bearer_token_env_var`），并且 Cursor 接受 `"Bearer ${env:NEXCMP_KEY}"`。切勿提交包含密钥的文件。
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

一次完整的运行（已于30/10/2026通过`openai-agents` 0.24验证——先进行读取工具操作，接着是余额变更，该操作返回了确认预览并在第二次调用`confirm_token`时应用）：

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

将服务器作为类型为 `mcp` 的工具传递。将 `require_approval` 保持在 `always` 上，以便你的程序在每次调用前向你询问：

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### 其他任何客户端（纯 HTTP） {#anything-else-plain-http}

没有 MCP 的客户端可以通过 HTTP 调用相同的工具。`GET /v1/admin/agent/tools` 列出它们，`POST /v1/admin/agent/tools/<name>` 运行带有参数 JSON 主体的工具，`GET /v1/admin/openapi.json` 返回 OpenAPI 3.1 描述（每个工具为一个操作）。所有这些都需要 `Authorization: Bearer ak_...`。

## 验证 {#verify}

1. 在没有客户端的情况下，列出工具：

   ```bash
   curl -s https://cloud.example.com/mcp/admin \
     -H "Authorization: Bearer ak_XXXX" \
     -H "Content-Type: application/json" \
     -H "Accept: application/json, text/event-stream" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
   ```

   返回结果为包含你的作用域所允许的工具的 JSON-RPC 结果。
2. 在你的客户端中询问“run system_health”。它会返回警报、所连接基础设施的健康状态、支付、电子邮件、AI 以及许可状态。
3. 打开**API & AI agents › Activity**：调用会与客户端名称以及`mcp`一同列出。
4. 在服务器端，`sudo nexcmp status` 会打印一行“MCP admin”，当端点响应时该行会显示 `ready`（没有密钥时返回 HTTP 401 是健康状态）。

## 工具 {#tools}

服务器提供 58 个工具。客户端只能看到其密钥的作用域所允许的工具：读取工具需要 `admin:read`，写入工具需要其自己的作用域。写入工具还会获得一个可选的 `confirm_token` 参数（参见 [Confirmation](#confirmation-confirm-token)）。系统会根据每个工具的架构检查参数：未知或类型错误的参数将被拒绝，并返回包含其名称的消息。

价格以美元计：套餐价格为每小时多少美元（`hourly_usd`），余额以美分计。可以设置机密信息，但绝不会将其返回。

### 概览与日志 {#overview-and-logs}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `system_health` | 需要注意的警报、基础设施健康状态、支付、电子邮件、AI、许可以及更新状态。 | `admin:read` | 否 | 否 |
| `setup_checklist` | 已配置的内容与剩余的内容：许可证、基础设施、区域、OS 模板、套餐、支付、电子邮件、品牌、法律条款、测试订单。 | `admin:read` | 否 | 否 |
| `license_status` | 许可证状态以及是否存在更新的 NexCMP 版本。 | `admin:read` | 否 | 否 |
| `audit_search` | 搜索管理员审计日志和 API 密钥日志。 | `admin:read` | 否 | 否 |

### 设置、品牌、法律条款、模块 {#settings-branding-legal-modules}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `settings_get` | 读取通用设置（`keys` 过滤器；尾随的 `*` 匹配前缀）。 | `admin:read` | 否 | 否 |
| `settings_update` | 从扁平的 `values` 对象更改通用设置。仅接受 `settings_get` 列出的键。 | `settings:write` | 是 | 当密钥涉及支付、登录安全、全站开关或价格时 |
| `branding_get` | 品牌名称、颜色、显示货币、卖家名称、徽标和 favicon URL。 | `admin:read` | 否 | 否 |
| `branding_update` | 设置品牌名称（最多 60 个字符）、颜色（`#rrggbb`）、显示货币（`usd` 或 `vnd`）以及卖家名称。 | `settings:write` | 是 | 否 |
| `branding_logo_set` | 通过 https URL 或 base64（PNG、JPEG、WEBP、ICO 或 SVG，最大 512 KB）上传亮色/暗色 Logo 或网站图标（favicon）。 | `settings:write` | 是 | 否 |
| `legal_get` | 服务条款与隐私政策（英文和越南文）以及中立的默认设置。 | `admin:read` | 否 | 否 |
| `legal_update` | 设置条款和隐私文本（简单 Markdown，不支持 HTML，每个最大 50 KB）。空字符串将恢复默认值。 | `settings:write` | 是 | 否 |
| `modules_get` | 哪些可选模块已开启，哪些可以切换。 | `admin:read` | 否 | 否 |
| `module_set` | 开启或关闭某个可选模块（`key` 必须是 `settable` 之一）。 | `settings:write` | 是 | 否 |

### 邮件与警报 {#email-and-alerts}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `smtp_get` | 外发邮件设置（密码已掩码）及队列状态。 | `admin:read` | 否 | 否 |
| `smtp_configure` | 设置 SMTP 服务器。更改主机、端口或安全性需要重新输入密码。 | `settings:write`（密码需加 `secrets:write`） | 是 | 否 |
| `smtp_test` | 使用保存的设置发送一封真实的测试邮件。 | `settings:write` | 发送邮件 | 否 |
| `telegram_get` | 管理员通知渠道（聊天 ID；从不返回机器人 Token）。 | `admin:read` | 否 | 否 |
| `telegram_configure` | 添加或更新 Telegram 警报渠道（机器人 Token 和聊天 ID），并开启或关闭管理员警报。 | `settings:write`（Token 需加 `secrets:write`） | 是 | 否 |
| `telegram_test` | 向 Telegram 渠道发送测试消息。 | `settings:write` | 发送消息 | 否 |

### 支付与货币 {#payments-and-currency}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `payments_get` | Stripe、PayPal、加密货币（USDT）及银行转账的状态，外加已启用的渠道和费用。 | `admin:read` | 否 | 否 |
| `payment_configure` | 设置单个网关的凭据（`stripe`、`paypal`、`crypto` 或 `bank`）。 | `billing:write` (+ `secrets:write`) | 是 | 始终 |
| `payment_test` | 与提供商核对网关保存的凭据。 | `billing:write` | 否 | 否 |
| `currency_get` | 显示货币及 USD 对 VND 的汇率（自动或手动）。 | `admin:read` | 否 | 否 |
| `currency_set` | 设置显示货币和/或手动汇率（0 表示自动，否则为 15000 至 50000）。 | `billing:write` | 是 | 当你更改手动汇率时 |

### 基础设施与可用区 {#infrastructure-and-zones}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `cloudstack_get` | 已保存的 CloudStack 端点、可用区及网络 ID（密钥已掩码）。 | `admin:read` | 否 | 否 |
| `cloudstack_test` | 在不保存的情况下使用 API Key 和 Secret 测试端点；列出可用区。 | `infra:write`（因为您传递了密钥，需加 `secrets:write`） | 否 | 否 |
| `cloudstack_connect` | 保存 CloudStack 连接。 | `infra:write` (+ `secrets:write`) | 是 | 始终 |
| `proxmox_list` | 作为源添加的 Proxmox VE 集群及其健康状态。 | `admin:read` | 否 | 否 |
| `proxmox_add` | 使用 API Token（`user@realm!tokenid`）及其 Secret 添加 Proxmox VE 集群。 | `infra:write` (+ `secrets:write`) | 是 | 否 |
| `proxmox_test` | 通过ID连接集群；首次成功连接会固定其TLS证书。 | `infra:write` | 是 | 否 |
| `proxmox_attach_zone` | 在现有区域中销售Proxmox集群，可选地将某个节点作为区域。 | `infra:write` | 是 | 否 |
| `zones_list` | 客户可以选择的区域（地理位置）。 | `admin:read` | 否 | 否 |
| `zone_create` | 创建一个区域。 | `infra:write` | 是 | 否 |

### 目录与套餐 {#catalog-and-plans}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `templates_list` | 客户可以安装的操作系统模板。 | `admin:read` | 否 | 否 |
| `templates_sync` | 从CloudStack导入操作系统模板。 | `catalog:write` | 是 | 否 |
| `template_update` | 启用或隐藏模板、重命名、设置登录用户或排序。 | `catalog:write` | 是 | 否 |
| `offerings_list` | 用于构建套餐的CloudStack服务套餐（CPU、内存、根磁盘）。 | `admin:read` | 否 | 否 |
| `plans_list` | 包含每小时及每月价格、规格、区域以及使用服务器数量的套餐。 | `admin:read` | 否 | 否 |
| `plan_create` | 创建一个套餐。价格格式为`hourly_usd`。CloudStack套餐需要`cs_offering_id`；Proxmox套餐需要`backend_id`。 | `catalog:write` | 是 | 否 |
| `plan_update` | 重命名、显示或隐藏、启用或禁用、或重新定价套餐。正在使用中的套餐修改规格需要进行复制。 | `catalog:write` | 是 | 当价格发生变化时 |
| `plans_from_offerings` | 使用您的成本和利润百分比从套餐（或Proxmox规格）构建入门套餐表。返回预览；再次调用并带上`apply=true`即可创建套餐。 | `catalog:write` | 带`apply=true` | 始终直接应用 |
| `quota_defaults_get` | 默认客户限制。 | `admin:read` | 否 | 否 |
| `quota_defaults_set` | 更改`quota_*`设置。 | `catalog:write` | 是 | 否 |
| `coupons_list` | 折扣和礼品码批次。 | `admin:read` | 否 | 否 |
| `coupon_create` | 创建一批代码：类型`money`（面值以美元分为单位）或`percent`（1到100，带最大折扣）。 | `catalog:write` | 是 | 始终 |

### 客户和分销商 {#customers-and-resellers}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `customers_search` | 通过电子邮件、姓名或IP查找客户。 | `admin:read` | 否 | 否 |
| `customer_get` | 单个客户的账户、余额、服务器和近期账单。 | `admin:read` | 否 | 否 |
| `customer_adjust_balance` | 添加（正数）或扣除（负数）以美元分为单位的信用额度。必须填写原因。 | `billing:write` | 是 | 始终 |
| `customer_block` | 封禁客户，可选择同时停止其服务器。必须填写原因。 | `customers:write` | 是 | 始终 |
| `customer_unblock` | 解封客户。 | `customers:write` | 是 | 否 |
| `resellers_list` | 带有钱包和状态的分销商。 | `admin:read` | 否 | 否 |
| `reseller_get` | 单个分销商的站点、钱包、用户和网关。 | `admin:read` | 否 | 否 |

### AI 提供商 {#ai-provider}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `ai_provider_get` | 客户AI Chat和AI Agent使用的OpenAI兼容提供商（密钥已掩码）。 | `admin:read` | 否 | 否 |
| `ai_provider_set` | 设置提供商：基础URL、模型、API密钥、回退模型、推理力度、启用状态。 | `ai:write`（密钥附加`secrets:write`） | 是 | 否 |
| `ai_provider_test` | 向保存的提供商询问一个问题以检查其是否正常工作。 | `ai:write` | 否 | 否 |

### 配置文件 {#configuration-files}

| 工具 | 功能说明 | 权限范围 | 更改数据 | 询问你 |
|---|---|---|---|---|
| `config_export` | 将配置导出为YAML（密钥变为`secret://`引用）。 | `admin:read` | 否 | 否 |
| `config_plan` | 将YAML配置与实时面板进行对比并列出将要更改的内容。 | `admin:read` | 否 | 否 |
| `config_apply` | 逐节应用YAML配置。每项更改都遵循常规作用域和确认规则。 | `admin:read` + 每项更改的作用域 | 是 | 每次更改 |

有关文件格式，请参见[Configuration as code](https://nexcmp.com/zh-cn/docs/configure-with-ai/config-as-code/)。

## 提示词 {#prompts}

服务器还提供三个现成提示词，客户端可将其显示为快捷方式：

| 提示词 | 参数 | 它要求AI执行的操作 |
|---|---|---|
| `initial-setup` | 无 | 调用`setup_checklist`，用一句话解释每个开放步骤，向其索取所需信息，用匹配的工具执行该步骤，预览资金或安全更改，最后以`system_health`结束。 |
| `add-proxmox` | `endpoint`（可选，`https://host:8006`） | 索取API令牌，然后使用`proxmox_add`、`proxmox_test`、区域工具和`proxmox_attach_zone`；接着用`plans_from_offerings`提出套餐建议并等待您的批准。 |
| `launch-pricing` | `margin_pct`（可选，默认40） | 询问您每个vCPU、每GB内存和每GB磁盘的每月成本，显示包含成本、每月价格和每小时价格的预览表，并在您批准后创建套餐。 |

## 确认（`confirm_token`） {#confirmation-confirm-token}

涉及资金转移、删除数据、更改支付凭证或登录安全的操作为两步式：

1. 第一次调用不作任何更改。工具结果以“CONFIRMATION REQUIRED”开头，并包含一个**预览**（将要调用的内容、为什么敏感、新值与当前值）以及一个`confirm_token`。
2. 客户端必须向您展示预览。只有在您批准后，它才会使用相同的参数外加`confirm_token`再次调用相同的工具。
3. 该令牌仅对该确切请求有效一次，并在5分钟后过期。

服务器指令告知AI应将工具结果视为数据而非指令，且绝不要用未获批准的Token重复调用。您是最后的防线：请仔细阅读预览。

::: warning 切勿自动批准
某些客户端可能会自动批准每个工具调用。对于写入类工具，请保持逐次调用批准开启，或使用只读密钥，以防AI的错误操作在未被察觉的情况下触及您的面板。
:::

## 工作原理 {#how-it-works}

| 项目 | 详情 |
|---|---|
| 传输 | `POST /mcp/admin`使用JSON-RPC 2.0消息；响应为`application/json`。单批次最多20条消息。`GET /mcp/admin`响应405（无服务器流）；`DELETE /mcp/admin`结束会话。 |
| 认证 | `Authorization: Bearer ak_...`（手动密钥或OAuth访问令牌）。缺少或错误的凭据会返回带有`WWW-Authenticate: Bearer ... resource_metadata=...`的401，这允许OAuth客户端自行开始登录。 |
| 会话 | `Mcp-Session-Id`由`initialize`签发，绑定至该密钥且有效期为24小时。 |
| 功能 | 仅限工具和提示词，无资源。 |
| 大小 | 请求体最大1 MB；工具结果在约100 KB后会被截断。 |
| 来源 | 带有来自其他站点的`Origin`请求头的请求将被拒绝（`origin_not_allowed`）。命令行和桌面客户端不会发送此头。 |
| 与REST相同的关卡 | 每个工具调用都会通过面板自身的请求管道并使用您的密钥重新发送，因此作用域、IP范围、速率限制、确认和活动日志的规则与直接调用API时完全一致。 |

## 限制与注意事项 {#limits-notes}

- 您看不到的工具即是您未授予的作用域。请将该作用域添加至新密钥中。
- 通过AI客户端设置密码或API密钥意味着该机密将经过该AI。如果您介意，请关闭`secrets:write`并在管理后台中自行输入机密，或使用AI Chat的**Secret**字段（位于[AI Chat in the admin](https://nexcmp.com/zh-cn/docs/configure-with-ai/ai-chat-in-admin/#secrets)）或`secret://`引用（[Configuration as code](https://nexcmp.com/zh-cn/docs/configure-with-ai/config-as-code/#secrets)）。
- 客户端不共享会话：每个连接均以`initialize`开始。
- 在**API & AI agents**中吊销密钥可立即切断AI客户端的连接。

## 故障排查 {#troubleshooting}

| 症状 | 原因 | 解决办法 |
|---|---|---|
| 401 `invalid_key` | 密钥错误、被截断或非管理员密钥（例如某个`vk_`密钥） | 请使用一个`ak_`密钥。 |
| 401 `key_expired` 或 `key_revoked` | 密钥已用尽或已被吊销 | 创建一个新密钥。 |
| 403 `ip_not_allowed` | 您的IP超出了密钥的IP范围 | 请从允许的IP进行连接。 |
| 403 `origin_not_allowed` | 来自其他来源的浏览器页面调用了该端点 | 请使用桌面或CLI客户端。 |
| 带有`Mcp-Session-Id`的请求返回404 | 会话属于其他密钥或已过期 | 请再次发送`initialize`。 |
| 400不支持的`MCP-Protocol-Version` | 客户端使用了服务器无法识别的版本 | 请更新客户端；支持的版本：2025-11-25、2025-06-18、2025-03-26。 |
| 工具列表很短 | 密钥作用域 | 请创建一个包含更多作用域的密钥。 |
| 调用时出现`insufficient_scope` | 工具需要第二个作用域，例如`secrets:write` | 请将该作用域添加至新密钥中。 |
| 429 `rate_limited` | 每分钟调用次数超出了密钥允许的限制 | 请等待`Retry-After`或在新密钥上提高限制。 |
| claude.ai或ChatGPT无法连接 | 无法从互联网访问该URL，或者代理阻止了`/mcp/admin`或`/oauth-admin/` | 请检查DNS、TLS和反向代理。 |

有关所有错误代码，请参阅[Admin API keys](https://nexcmp.com/zh-cn/docs/configure-with-ai/admin-api-keys/#errors)。