---
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) を呼んでアカウントを管理させます。サーバーは薄いトランスポートと認証のシェルです。管理操作ごとに 1 つの MCP ツールを公開し、各呼び出しを API へプロキシします。なのでエージェントは、請求を除き、あなたができることなら何でも、自然言語でできます。

## アクセストークンを発行する [#mint-an-access-token]

サーバーは `CAPUTCHIN_TOKEN` 環境変数のアクセストークンで認証します。どちらの種類も動きます（[API 認証](/docs/automation/management-api#mint-an-access-token) を参照）：

- アカウント全体の制御のための [Personal Access Token](/docs/account-management/personal-access-token)、または
- 最小権限でエージェントを特定のチームにスコープづけする [Troop Access Token](/docs/troops/tokens)。自律エージェントにアクセスを渡すときの、より安全な既定です。

作成時にトークンをコピーしてください。一度だけ表示されます。

## つなぐ 2 つの方法

2 つのトランスポートがあり、それらは同じ管理 API に裏打ちされた **同じツール** を公開します。クライアントがどうつなぐかで選んでください：

| | ローカル（stdio） | ホスト型（HTTP） |
|---|---|---|
| それは何か | あなたのマシンで走る `@caputchin/mcp` パッケージ | `api.caputchin.com/mcp` のリモートエンドポイント |
| クライアントに必要なもの | ローカルプロセスを起動すること（stdio） | リモート MCP サーバーにつなぐこと（HTTP） |
| 認証 | プロセス環境の `CAPUTCHIN_TOKEN` | 接続上の `Authorization: Bearer` ヘッダー |
| 最適なとき | ローカル開発、デスクトップクライアント、インバウンドネットワークなし | ホスト型エージェント、起動するローカルプロセスなし |

### ローカル：npx サーバー（stdio）

サーバーは npm に `@caputchin/mcp` として公開されています。たいてい手で実行はしません。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>` と名付けられ、1 つの管理操作に対応します。たとえば `caputchin_list_troops`、`caputchin_create_site`、`caputchin_rotate_site_secret`、`caputchin_add_troop_member`、`caputchin_site_stats` です。エージェントは MCP 越しに全セットと各ツールのパラメータを自動で発見するので、あなたは目標を述べ、エージェントがツールを選びます。

## 実例

サーバーをクライアントに組み込んだら、エージェントに平易な言葉で頼めます：

> 「私の shop-team チームに shop-frontend という名前のサイトキーを作って、それからそれのゲームゲートをオンにして。」

エージェントはそれを一連のツール呼び出しに解決します。チーム id を見つける `caputchin_list_troops`、その `troop_id` を伴う `caputchin_create_site`、それからゲームを必須にする `caputchin_update_site_security` です。各呼び出しはあなたのトークンで管理 API に当たり、Apex では各々がトークンに帰属して [監査ログ](/docs/audit-logs/overview) に着地するので、エージェントの行動は人のものと同じくらい追跡できます。

エージェントはあなたのトークンの全到達範囲で動くので、できるときはスコープづけされたチームトークンを選び、タスクが終わった瞬間にそれを失効させてください。

## 完全なリファレンス

ツールの完全な一覧を、それぞれの 1 行の説明と、そのトークンが持たなければならない権限とともに見るには、[MCP ツールリファレンス](/docs/automation/mcp-tools) を参照してください。ツールは管理 API を 1 対 1 で映すので、[インタラクティブ API リファレンス](/docs/api-reference) が、すべての操作のパラメータとレスポンスの権威ある説明です。エージェント向けの要約にはツールの MCP 説明を、正確なスキーマには API リファレンスを読んでください。

## あわせて読む

- [MCP ツールリファレンス](/docs/automation/mcp-tools)：すべてのツール、その説明、必要な権限。
- [API から Caputchin を管理する](/docs/automation/management-api)：すべてのツールが呼ぶ HTTP API。
- [Terraform または OpenTofu を使う](/docs/automation/terraform)：infrastructure-as-code の面。
- [Personal Access Token](/docs/account-management/personal-access-token) と [チームトークン](/docs/troops/tokens)：サーバーが使う資格情報。