---
title: MCPサーバー
description: Claude、Cursor、VS CodeなどのAIアシスタントを、/mcpにある組み込みMCPエンドポイント経由でインストール先のAPIに接続します（認証、クライアント設定、ツール、安全規則）。
url: https://nexcmp.com/ja/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# MCPサーバー {#mcp-server}

> **ポータル内の場所:** API reference › Tools (`https://<your-domain>/apidoc`) にエンドポイントとクライアントのコードスニペットが表示されます。キーは API keys (`/api-keys`) で作成します。管理画面側での設定はなく、エンドポイントはパネルの一部として組み込まれています。

## 動作内容 {#what-it-does}

**Model Context Protocol (MCP)**により、AIアシスタントはツールを呼び出すことができます。NexCMPは`https://<your-domain>/mcp`でMCPエンドポイントを提供します。すべての公開API操作が1つの**ツール**（`vm_list`、`vm_start`、`billing_wallet`、...）になるため、顧客はアシスタントに「実行中のVMはどれ？」や「ステージング用VMを停止して」と尋ねることができます。アシスタントは顧客自身のAPIキーと権限でのみ動作します。

::: tip NexCMP自体をAIで設定しますか？
このページは**顧客側**のMCPエンドポイント（`/mcp`）です。管理者として独自のパネルをAIアシスタントに設定させるには、[Configure with AI](https://nexcmp.com/ja/docs/configure-with-ai/mcp-admin/)（エンドポイント`/mcp/admin`、管理者キー`ak_`）をご覧ください。
:::

## 要件 {#requirements}

| 項目 | 要件 |
|---|---|
| サーバー | インストールは不要です。エンドポイントはパネルによって提供され、パネルが到達可能な場所であればどこからでもアクセスできます。リバースプロキシは`/mcp`をパネルに転送する必要があります。 |
| 顧客 | アシスタントに必要なスコープを持つ[APIキー](https://nexcmp.com/ja/docs/developers/api-keys/)（`vk_...`）。 |
| クライアント | **Streamable HTTP**トランスポートとカスタム`Authorization`ヘッダーをサポートするMCPクライアント: Claude Code、Claude Desktop（`mcp-remote`ブリッジ経由）、Cursor、Copilotエージェントモードを有効にしたVS Codeなど。 |
| プロトコルバージョン | 2025-11-25、2025-06-18、2025-03-26。 |

## インフラストラクチャの準備 {#prepare-the-infrastructure}

`https://<your-domain>/mcp`がファイアウォールやプロキシのルールによってブロックされていないことを確認する以外に、特にありません。別オリジンからのブラウザベースのMCPクライアントはそのオリジンが許可されていない限り拒否されますが、コマンドラインおよびデスクトップクライアントは`Origin`ヘッダーを送信せず、そのまま動作します。

## 接続（顧客側） {#connect-customer-side}

1. アシスタントに使用させたいスコープのみ、短い有効期限、および可能であればIP制限を設定して、ポータル（**API keys › Create key**）でAPIキーを作成します。
2. クライアントにサーバーを追加します。`cloud.example.com`とキーを置き換えてください。

   **Claude Code**

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

   **Cursor**（`~/.cursor/mcp.json`または`.cursor/mcp.json`。Cursorが起動する環境で`CLOUD_API_KEY`を設定してください）:

   ```json
   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop**（Node.js 18以上が必要; `claude_desktop_config.json`）、`mcp-remote`ブリッジ経由:

   ```json
   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }
   ```

   コロンの後にスペースを入れずにヘッダーを記述し、上記のように値全体を環境変数に設定してください。

3. クライアントを再起動し、ツールの一覧を表示するよう指示します。


クライアントなしで接続を確認する:

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

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

| 項目 | Detail |
|---|---|
| Endpoint | JSON-RPC 2.0メッセージによる`POST /mcp`。応答は`application/json`です。`GET /mcp`は405（サーバーからクライアントへのストリームなし）を返します。`DELETE /mcp`はセッションを終了します。 |
| 認証 | `Authorization: Bearer vk_...`のみ（セッション トークン、クッキー、管理者キーは401および`WWW-Authenticate: Bearer`ヘッダーと共に拒否されます）。 |
| セッション | `Mcp-Session-Id`は`initialize`によって発行され、そのキーに紐付けられ、有効期間は24時間です（1キーあたり最大16セッション）。 |
| ツール | キーから参照できる公開API操作ごとに1つ。ツール名は、スペースとダッシュを`_`に置き換えたCLIコマンドであり（`vm firewall add`は`vm_firewall_add`になる）、OpenAPIの`operationId`と一致します。ツールは、キーがそのスコープを持ち、モジュールが有効化されている場合にのみ一覧に表示されます。 |
| 機能 | ツールのみ（リソースやプロンプトはなし）。 |
| サイズ | リクエストボディは最大1MB、ツール結果のテキストは約100KBまで（残りは注記付きで切り捨てられます）。1回の呼び出しは最大55秒です。 |

### 安全規則 {#safety-rules}

- **RESTと同一のゲート。**各 `tools/call` は、パネル自体のリクエストパイプライン（スコープ、サイト、IP制限、レートリミット、べき等性、所有権チェック［他人のリソースの場合は404］、およびクォータ）を通過します。キーが持っていない権限をMCPが与えることはできません。
- **確認。**課金を伴う、削除を行う、または認証情報を返すツール（コンソールチケット、kubeconfig、S3またはSSHのシークレット、パスワードリセット、新しいキー）では、引数 `confirm: true` が必須となります。ツール説明では、ユーザーが承認した後にのみこれを渡すようアシスタントに指示するため、Webページやログに隠された指示単体で実行されることはありません。
- **べき等性。**有料ツールでは `idempotency_key` を受け付けます。省略された場合はツール名と引数から安定したキーが導出されるため、同一のリトライで二重に課金されることはありません。
- **ツールとして公開されないもの：**ストリーミングエンドポイント（AI Agentのチャット）、ワンタイムのSSHまたはコンソールWebSocketチケット、バイナリダウンロード、およびVPNアプリのエンドポイント（`/v1/ext/*`）。
- **絶対に不可能なこと：**APIでは、トップアップ、パスワード変更、アカウントの削除、キーの作成は一切許可されていないため、どのアシスタントもこれらを実行できません。

### 制限事項 {#limits}

| 制限 | デフォルト |
|---|---|
| キーあたりのツール呼び出し数 | 60回 / 分 |
| キーあたりのMCPリクエスト数 | 240回 / 分 |
| 通常のキーおよびアカウントの制限に準じる | [REST API](https://nexcmp.com/ja/docs/developers/api/#rate-limits)を参照 |

制限を超えた場合、エンドポイントはJSON-RPCエラーと `Retry-After` を添えてHTTP 429を返します。

## 確認 {#verify}

1. 上記の `curl` コマンドは、 `tools` リストを含むJSON-RPC結果を返します。キーのスコープに一致するツールのみが表示されます。
2. クライアントで「VMの一覧を表示して」と尋ねると、アシスタントが `vm_list` を呼び出して結果を表示します。
3. ポータル内のキーの **Last used** 時刻が更新され、書き込み呼び出しが **Key usage log** に表示されます。

## 制限と注意事項 {#limits-notes}

- **ブラウザサインイン（OAuth）。**リファレンスページでは、MCP OAuthをサポートするクライアント向けにブラウザ経由のサインインについても説明しています。インストール済みのNexCMPにおいて、サポートおよびテスト済みの方法はAPIキー（またはCLIの場合は `cmp login`）です。
- **リセラーサイト**ではMCPセクションは表示されません。そのお客様はAPIにリセラーのドメインを使用します。
- **最小権限の原則。**まず読み取りスコープを持つ専用のキーをアシスタントごとに作成し、必要な場合にのみ書き込みスコープを追加してください。
- **API keys** でキーを失効させると、アシスタントからのアクセスを即座に遮断できます。

## トラブルシューティング {#troubleshooting}

| 症状 | 原因 | 対処法 |
|---|---|---|
| `WWW-Authenticate: Bearer` を伴う401 | キーなし、誤ったキー、またはセッショントークン | `Authorization: Bearer vk_...` を送信してください。 |
| `Origin` に関する403 | 別オリジンのブラウザページ | デスクトップまたはCLIクライアントを使用するか、管理者にオリジン（`mcp_allowed_origins`）の許可を依頼してください。 |
| `Mcp-Session-Id` を伴うリクエストでの404 | セッションが別のキーに属しているか、期限切れです | もう一度 `initialize` を実行してください。 |
| `GET /mcp` における405 | 想定される原因：サーバーにイベントストリームがありません | POSTのみを使用してください（クライアントはこれを自動的に行います）。 |
| ツールリストが短い | キーのスコープまたはモジュール | キーにスコープを追加し、モジュールを有効にしてください。 |
| `confirm: true` が必要であるとツールが応答する | 有料、削除、または機密性の高いツール | あなたが承認した後、アシスタントは `confirm` を設定する必要があります。 |
| 429 | MCPまたはキーのレートリミット | `Retry-After` までお待ちください。 |
| クライアントがヘッダー付きで接続できない | カスタムヘッダーをサポートしていないクライアント | `mcp-remote` ブリッジを使用してください。 |