---
title: AIクライアントの接続 (MCP)
description: Claude Code、Codex CLI、Gemini CLI、Cursor、Claude Desktop、claude.ai、ChatGPT、OpenAI SDKをパネルのadmin MCPエンドポイントに接続し、すべてのツールを利用できます。
url: https://nexcmp.com/ja/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クライアントがツールを呼び出せるようになります。パネルは管理用MCPサーバーを `https://cloud.example.com/mcp/admin` で公開します。独自のAIツールを接続し、自然言語で「何をセットアップする必要がありますか？」「Proxmoxクラスターを追加して」「40%の利益率でプランを作成して」などと質問できます。クライアントは以下の管理者ツールを呼び出し、パネルはスコープを確認し、リスクのある操作の前に確認を求め、すべての呼び出しを記録します。

::: info 2つのMCPエンドポイント
`/mcp` は**顧客**エンドポイント（顧客用APIキー、`vk_`、[MCP server](https://nexcmp.com/ja/docs/developers/mcp/)を参照）です。`/mcp/admin` は、ここで説明する**管理者**エンドポイント（管理者キー `ak_` またはOAuth）です。これら2つが混ざることはありません。管理者ツールは `/mcp` では表示されず、`/mcp/admin` は管理者キーのみを受け付けます。
:::

## 要件 {#requirements}

| 項目 | 要件 |
|---|---|
| Endpoint | パネル自体のドメイン上の `https://cloud.example.com/mcp/admin`。**Connect an AI**タブから正確なURLをコピーします。同じページに、サーバー上で実行されるツール用のローカルURL（`http://127.0.0.1:<port>/mcp/admin`）も記載されています。 |
| 資格情報 | 必要なスコープを持つ[管理者APIキー](https://nexcmp.com/ja/docs/configure-with-ai/admin-api-keys/)（`ak_...`）、**または**ウェブコネクター用のOAuthサインイン（[OAuth connectors](https://nexcmp.com/ja/docs/configure-with-ai/oauth-connectors/)）。 |
| クライアント | **Streamable HTTP**転送とカスタム `Authorization` ヘッダーをサポートする任意のMCPクライアント。プロトコルバージョン 2025-11-25、2025-06-18、2025-03-26。 |
| ネットワーク | パネルの前段に独自のリバースプロキシを配置する場合は、`/mcp/admin`を転送する必要があります。ウェブコネクター（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/ja/docs/configure-with-ai/admin-api-keys/)を参照してください。
2. **Connect an AI**タブを開きます。「キーが作成されました」ダイアログが表示されている間は、以下のスニペットすべてに実際のキーがすでに含まれています。それ以外の場合はプレースホルダー `ak_YOUR_KEY` が表示されます。
3. クライアント用のスニペットをコピーし、次の説明に従って実行または貼り付けます。

![MCPのURLとクライアントごとのコピーボタン付きカードが表示されたConnect an AIタブ](https://nexcmp.com/ja/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` を起動し、「list the tools from nexcmp」または「what is left to set up?」と質問します。

2026/10/30に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/ja/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/ja/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を起動するシェルでキーをエクスポートします:

```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]`配下に追加します。パネルは引き続きプレビューを返し、金銭、セキュリティ、削除のアクションについては確認を求めます。2026/10/30に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サーバーを無効にします。信頼するフォルダー内で起動するか（または求められた際にフォルダーを信頼）、`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で確認 — 読み取りツールの後、確認プレビューを返し、2回目の`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の記述（各ツールが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)を参照）。引数は各ツールのスキーマに対して検証され、不明な引数や型の間違った引数は、該当する引数名を挙げて拒否されます。

価格はUSD建てです。プラン価格は1時間あたりのドル（`hourly_usd`）、残高はセント単位です。シークレットは設定可能ですが、取得されることはありません。

### 概要とログ {#overview-and-logs}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `system_health` | 注意が必要なアラート、インフラストラクチャの健康状態、決済、メール、AI、ライセンス、およびアップデート状況。 | `admin:read` | いいえ | いいえ |
| `setup_checklist` | 設定済みの項目と残りの項目: ライセンス、インフラストラクチャ、ゾーン、OSテンプレート、プラン、決済、メール、ブランディング、法的事項、テスト注文。 | `admin:read` | いいえ | いいえ |
| `license_status` | ライセンスのステータスと、より新しいNexCMPのバージョンが存在するかどうか。 | `admin:read` | いいえ | いいえ |
| `audit_search` | 管理者の監査ログとAPIキーログを検索する。 | `admin:read` | いいえ | いいえ |

### 設定、ブランディング、法的事項、モジュール {#settings-branding-legal-modules}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `settings_get` | 一般設定を読み取る（`keys`はフィルター。末尾の`*`はプレフィックスに一致）。 | `admin:read` | いいえ | いいえ |
| `settings_update` | フラットな`values`オブジェクトから一般設定を変更する。`settings_get`によってリストされたキーのみが受け付けられます。 | `settings:write` | はい | キーが決済、サインインセキュリティ、サイト全体のスイッチ、または価格に影響する場合 |
| `branding_get` | ブランド名、色、表示通貨、販売者名、ロゴおよびファビコンのURL。 | `admin:read` | いいえ | いいえ |
| `branding_update` | ブランド名（60文字以内）、色（`#rrggbb`）、表示通貨（`usd`または`vnd`）、販売者名を設定する。 | `settings:write` | はい | いいえ |
| `branding_logo_set` | httpsのURLまたはbase64（PNG、JPEG、WEBP、ICO、SVG、最大512 KB）から、ライト/ダークロゴまたはファビコンをアップロードします。 | `settings:write` | はい | いいえ |
| `legal_get` | 利用規約とプライバシーポリシー（英語およびベトナム語）、およびニュートラルなデフォルト設定。 | `admin:read` | いいえ | いいえ |
| `legal_update` | 規約とプライバシーのテキストを設定します（シンプルなマークダウン、HTML不可、各最大50 KB）。空文字列を指定するとデフォルトに戻ります。 | `settings:write` | はい | いいえ |
| `modules_get` | 有効になっているオプションモジュールと、切り替え可能なモジュール。 | `admin:read` | いいえ | いいえ |
| `module_set` | オプションモジュールの有効/無効を切り替えます（`key`は`settable`のいずれかである必要があります）。 | `settings:write` | はい | いいえ |

### メールとアラート {#email-and-alerts}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `smtp_get` | 送信メール設定（パスワードはマスク表示）とキューの状態。 | `admin:read` | いいえ | いいえ |
| `smtp_configure` | SMTPサーバーを設定します。ホスト、ポート、またはセキュリティを変更する場合は、再度パスワードの入力が必要です。 | `settings:write`（パスワード用に`secrets:write`を追加） | はい | いいえ |
| `smtp_test` | 保存済みの設定を使用して、実際のテストメールを送信します。 | `settings:write` | メールを送信します | いいえ |
| `telegram_get` | 管理者通知チャネル（チャットID。ボットトークンは一切返されません）。 | `admin:read` | いいえ | いいえ |
| `telegram_configure` | Telegramアラートチャネル（ボットトークンとチャットID）の追加または更新を行い、管理者アラートの有効/無効を切り替えます。 | `settings:write`（トークン用に`secrets:write`を追加） | はい | いいえ |
| `telegram_test` | Telegramチャネルにテストメッセージを送信します。 | `settings:write` | メッセージを送信します | いいえ |

### 決済と通貨 {#payments-and-currency}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `payments_get` | Stripe、PayPal、暗号資産（USDT）、銀行振込の状態、および有効化されているチャネルと手数料。 | `admin:read` | いいえ | いいえ |
| `payment_configure` | 1つの決済ゲートウェイの認証情報を設定します（`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}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `cloudstack_get` | 保存済みのCloudStackエンドポイント、ゾーン、およびネットワークID（キーはマスク表示）。 | `admin:read` | いいえ | いいえ |
| `cloudstack_test` | 保存せずにAPIキーとシークレットでエンドポイントをテストし、ゾーンを一覧表示します。 | `infra:write`（キーを渡すため`secrets:write`を追加） | いいえ | いいえ |
| `cloudstack_connect` | CloudStack接続を保存します。 | `infra:write` (+ `secrets:write`) | はい | 常時 |
| `proxmox_list` | ソースとして追加されたProxmox VEクラスターと、その稼働状態。 | `admin:read` | いいえ | いいえ |
| `proxmox_add` | APIトークン（`user@realm!tokenid`）とそのシークレットを使用して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}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `templates_list` | お客様がインストールできるOSテンプレート。 | `admin:read` | いいえ | いいえ |
| `templates_sync` | CloudStackからOSテンプレートをインポートします。 | `catalog:write` | はい | いいえ |
| `template_update` | テンプレートの有効化/非表示、名前の変更、ログインユーザーや順序の設定を行います。 | `catalog:write` | はい | いいえ |
| `offerings_list` | プランの構築元となるCloudStackのサービスオファリング（CPU、メモリ、ルートディスク）。 | `admin:read` | いいえ | いいえ |
| `plans_list` | 1時間あたりおよび1か月あたりの料金、サイズ、ゾーン、およびそれらを利用しているサーバー数を含むプラン。 | `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}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `customers_search` | メールアドレス、名前、または IP で顧客を検索します。 | `admin:read` | いいえ | いいえ |
| `customer_get` | 1 人の顧客のアカウント、残高、サーバー、および最近の請求履歴。 | `admin:read` | いいえ | いいえ |
| `customer_adjust_balance` | 米ドルセント単位でクレジットを追加（プラス）または削除（マイナス）します。理由は必須です。 | `billing:write` | はい | 常時 |
| `customer_block` | 顧客をブロックし、必要に応じてサーバーを停止します。理由は必須です。 | `customers:write` | はい | 常時 |
| `customer_unblock` | 顧客のブロックを解除します。 | `customers:write` | はい | いいえ |
| `resellers_list` | ウォレットとステータスを持つリセラー。 | `admin:read` | いいえ | いいえ |
| `reseller_get` | 1 つのリセラーのサイト、ウォレット、ユーザー、および決済ゲートウェイ。 | `admin:read` | いいえ | いいえ |

### AIプロバイダー {#ai-provider}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `ai_provider_get` | 顧客の AI Chat および AI Agent が使用する OpenAI 互換プロバイダー（キーはマスクされています）。 | `admin:read` | いいえ | いいえ |
| `ai_provider_set` | プロバイダーを設定します: ベース URL、モデル、API キー、フォールバックモデル、推論の度合い、有効化。 | `ai:write` (キーの場合は `secrets:write`) | はい | いいえ |
| `ai_provider_test` | 正しく動作するか確認するため、保存されたプロバイダーに 1 つ質問します。 | `ai:write` | いいえ | いいえ |

### 設定ファイル {#configuration-files}

| ツール | 動作内容 | Scope | データの変更 | 確認の有無 |
|---|---|---|---|---|
| `config_export` | 設定を YAML としてエクスポートします（機密情報は `secret://` 参照になります）。 | `admin:read` | いいえ | いいえ |
| `config_plan` | YAML 設定と稼働中のパネルを比較し、変更される内容を一覧表示します。 | `admin:read` | いいえ | いいえ |
| `config_apply` | YAML 設定をセクションごとに適用します。各変更は通常のスコープおよび確認ルールに従います。 | `admin:read` + すべての変更のスコープ | はい | 変更ごと |

ファイル形式については [Configuration as code](https://nexcmp.com/ja/docs/configure-with-ai/config-as-code/) を参照してください。

## プロンプト {#prompts}

サーバーは、クライアントがショートカットとして表示できる 3 つの既製プロンプトも提供します:

| プロンプト | 引数 | AI に実行を求める内容 |
|---|---|---|
| `initial-setup` | なし | `setup_checklist` を呼び出し、未完了の各ステップを 1 文で説明し、必要な情報を尋ね、一致するツールでステップを実行し、金額やセキュリティの変更をプレビューして、`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 あたり、RAM の GB あたり、ディスクの GB あたりの月額コストを尋ね、コスト、月額料金、時間額料金を表示するプレビューテーブルを表示し、承認後にプランを作成します。 |

## 確認 (`confirm_token`) {#confirmation-confirm-token}

資金の移動、データの削除、支払い資格情報の変更、またはサインインセキュリティの変更を行うアクションは 2 ステップです:

1. 最初の呼び出しでは何も変更されません。ツール結果は "CONFIRMATION REQUIRED" で始まり、**プレビュー**（呼び出される内容、機密である理由、新しい値と現在の値）および `confirm_token` が含まれます。
2. クライアントはプレビューを表示する必要があります。あなたが承認した後にのみ、同じ引数に `confirm_token` を追加して同じツールを再度呼び出します。
3. トークンは 1 回限り、その正確なリクエストに対してのみ有効であり、5 分後に期限切れになります。

サーバーの指示により、AIはツール結果を命令ではなくデータとして扱い、承認されていないトークンで呼び出しを繰り返さないようになっています。お客様が最後の砦です。プレビューをご確認ください。

::: warning 自動承認を行わない
一部のクライアントはすべてのツール呼び出しを自動的に承認できます。書き込みツールについては、呼び出しごとの承認を有効にするか、読み取り専用キーを使用してください。これにより、AIの誤った計画が確認されずにパネルに到達するのを防げます。
:::

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

| 項目 | Detail |
|---|---|
| トランスポート | `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/ja/docs/configure-with-ai/ai-chat-in-admin/#secrets)）または`secret://`参照（[Configuration as code](https://nexcmp.com/ja/docs/configure-with-ai/config-as-code/#secrets)）をご利用ください。
- クライアント間でセッションは共有されません。各接続は`initialize`で始まります。
- AIクライアントを即座に遮断するには、**API & AI agents**でキーを無効化します。

## トラブルシューティング {#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 unsupported `MCP-Protocol-Version` | クライアントがサーバーの認識していないバージョンを使用しています | クライアントを更新してください。サポート対象：2025-11-25、2025-06-18、2025-03-26。 |
| ツールリストが短い | キースコープ | より多くのスコープを持つキーを作成してください。 |
| 呼び出し時の`insufficient_scope` | ツールに追加のスコープ（例：`secrets:write`）が必要です | 新しいキーにスコープを追加してください。 |
| 429 `rate_limited` | 1分あたりの呼び出し回数がキーの許容量を超えています | `Retry-After`まで待つか、新しいキーで制限を引き上げてください。 |
| claude.aiまたはChatGPTが接続できません | URLにインターネットから到達できないか、プロキシが`/mcp/admin`または`/oauth-admin/`をブロックしています | DNS、TLS、およびリバースプロキシを確認してください。 |

すべてのエラーコードについては[Admin API keys](https://nexcmp.com/ja/docs/configure-with-ai/admin-api-keys/#errors)を参照してください。