---
type: how-to
title: 使用 MCP 服务器
summary: 通过 MCP 服务器把一个 AI 代理连到 Caputchin、用一个访问令牌给它做身份验证、并用自然语言驱动管理 API，附一个完整示例。
---

Caputchin 的 MCP 服务器让一个 AI 代理（Claude、Cursor，或任何 [Model Context Protocol](https://modelcontextprotocol.io) 客户端）通过调用仪表盘所用的同一个 [管理 API](/docs/automation/management-api) 来管理你的账户。这个服务器是一层薄薄的传输与认证外壳：它为每个管理操作暴露一个 MCP 工具，并把每个调用代理到 API。于是这个代理用自然语言就能做你能做的任何事，除了账单。

## 铸造一个访问令牌 [#mint-an-access-token]

服务器用来自 `CAPUTCHIN_TOKEN` 环境变量的一个访问令牌做身份验证。两种都能用（见 [API 认证](/docs/automation/management-api#mint-an-access-token)）：

- 一个 [个人访问令牌](/docs/account-management/personal-access-token) 用于全账户控制，或
- 一个 [团队访问令牌](/docs/troops/tokens) 把代理以最小权限限定到某些团队上，这在把访问权交给一个自主代理时是更安全的默认。

在创建时复制令牌；它只显示一次。

## 两种连接方式

有两种传输，它们暴露 **同样的工具**，由同一个管理 API 支撑。按你的客户端如何连接来选：

| | 本地（stdio） | 托管（HTTP） |
|---|---|---|
| 它是什么 | `@caputchin/mcp` 包，跑在你的机器上 | 一个在 `api.caputchin.com/mcp` 的远程端点 |
| 客户端需要 | 生成一个本地进程（stdio） | 连接到一个远程 MCP 服务器（HTTP） |
| 认证 | 进程环境里的 `CAPUTCHIN_TOKEN` | 连接上的 `Authorization: Bearer` 头 |
| 最适合 | 本地开发、一个桌面客户端、无入站网络 | 一个托管的代理、没有本地进程可生成 |

### 本地：npx 服务器（stdio）

服务器作为 `@caputchin/mcp` 发布在 npm 上。你通常不手动跑它；你把它接进你 MCP 客户端的配置里，它就通过 stdio 被生成，令牌在它的环境里：

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

要检查它能跑，就直接启动它；它通过 stdio 讲 MCP，并在令牌缺失时带一个错误退出：

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### 托管：HTTP 端点

对于那些连接到一个远程 MCP 服务器、而非生成一个本地服务器的客户端，Caputchin 在这里托管同一个服务器：

```
https://api.caputchin.com/mcp
```

它用你的令牌作为连接上的一个 `Bearer` 头来做身份验证（同一份凭据，只是通过 HTTP 而非环境传递）：

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

确切的配置形状取决于你的 MCP 客户端；要紧的是那个 URL 和那个 `Authorization: Bearer` 头。没有什么要安装，也没有本地进程；代价是令牌每次请求都旅行到那个托管端点，而不是留在一个本地进程的环境里。

## 这些工具

每个工具都命名为 `caputchin_<verb>_<noun>`，并对应一个管理操作，例如 `caputchin_list_troops`、`caputchin_create_site`、`caputchin_rotate_site_secret`、`caputchin_add_troop_member`、`caputchin_site_stats`。代理通过 MCP 自动发现完整的集合和每个工具的参数，所以你描述目标，代理来挑工具。

## 一个完整示例

把服务器接进你的客户端后，你可以用大白话问代理：

> “在我的 shop-team 团队里创建一个叫 shop-frontend 的站点密钥，然后给它打开游戏关卡。”

代理会把那解析成一连串工具调用：`caputchin_list_troops` 找到团队 id、带那个 `troop_id` 的 `caputchin_create_site`、然后 `caputchin_update_site_security` 来要求一个游戏。每个调用都用你的令牌击中管理 API，而在 Apex 上每一个都落在你的 [审计日志](/docs/audit-logs/overview) 里、归到那个令牌名下，于是一个代理的行动和一个人的一样可追溯。

因为代理是以你令牌的完整触及范围在行动，能用就优先用一个限定范围的团队令牌，并在任务一完成就吊销它。

## 完整参考

完整的工具清单，每个带一行描述和它的令牌必须持有的权限，见 [MCP 工具参考](/docs/automation/mcp-tools)。这些工具和管理 API 一对一对应，所以 [交互式 API 参考](/docs/api-reference) 是每个操作的参数和响应的权威描述：读一个工具的 MCP 描述看面向代理的摘要，读 API 参考看确切的模式。

## 另见

- [MCP 工具参考](/docs/automation/mcp-tools)：每个工具、它的描述，以及它需要的权限。
- [从 API 管理 Caputchin](/docs/automation/management-api)：每个工具调用的那个 HTTP API。
- [使用 Terraform 或 OpenTofu](/docs/automation/terraform)：那个基础设施即代码的面。
- [个人访问令牌](/docs/account-management/personal-access-token) 和 [团队令牌](/docs/troops/tokens)：服务器所用的凭据。