Claude MCP 設定は、Claude Code または Claude Desktop をデータベース、コードランナー、API、カスタムサーバーなどの外部ツールに接続します。Claude Code では claude mcp add を使用し、Claude Desktop では JSON 設定を編集して、トランスポート、スコープ、ツールリストを確認します。このガイドでは、両方の設定方法、よくある問題、ツール使用の推論、サンドボックス実行について説明します。
Claude MCP 設定の仕組み
MCP は Anthropic によるオープンスタンダードで、言語モデルに外部ツールを呼び出すための統一された方法を提供します。MCP 以前は、すべての AI アプリが使用したいツールごとに個別のグルーコードを必要としていました。MCP では、準拠したサーバーは標準の検出および呼び出しプロトコルを通じて機能を公開し、Claude を含む準拠したホストはツールごとの統合作業なしでそれらを使用できます。
実際には、Claude に MCP サーバーを追加すると、Claude ホストにツールセットの場所を伝えることになります。Claude はセッション中にそれらのツールをリストし、タスクに応じて名前で呼び出すことができます。サーバーが実行を処理し、Claude がいつどのように呼び出すかの推論を処理します。
MCP を支える3つのコアコンセプト:
| 概念 | 説明 | 例 |
|---|---|---|
| Tool | サーバーが公開する呼び出し可能な関数 | run_python, query_db, list_models |
| Resource | サーバーがコンテキストとして利用可能にする読み取り専用データ | ファイル、データベースの行、データセット |
| Prompt | サーバーにバンドルされた事前構築済みの指示テンプレート | システムレベルのタスク説明 |
ほとんどの開発者にとって、ツールが最も重要です。リソースとプロンプトは、より構造化されたエージェントパイプラインを構築する際に関連してきます。
Claude Code で MCP サーバーを追加する
Claude Code は claude mcp サブコマンドグループを通じて MCP 管理を提供します。設定ファイルを手動で編集することなく、サーバーの追加、削除、一覧表示ができます。
claude mcp add — 基本形式
claude mcp add <name> <command> [args...]
例えば、ローカルの Python MCP サーバーを追加するには:
claude mcp add my-tools python /path/to/mcp_server.py
これにより、stdio トランスポートを使用して python /path/to/mcp_server.py を実行する my-tools という名前のサーバーが登録されます。Claude Code はセッション開始時にプロセスを起動し、セッション中はそれを維持します。
環境変数の渡し方
多くの MCP サーバーは API キーやエンドポイント URL を必要とします。登録時に --env を使用して渡します:
claude mcp add my-tools python /path/to/mcp_server.py \
--env API_KEY=your_key_here \
--env BASE_URL=https://api.example.com
値は Claude Code の設定に保存され、起動時にサーバープロセスに注入されます。シークレットをサーバーコマンド自体にハードコードしないでください。
claude mcp add json — JSON 仕様から登録する
サーバー仕様がすでに JSON で記述されている場合（チーム間で設定を共有する際によくあります）、直接パイプで渡すことができます:
echo '{
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key"
}
}' | claude mcp add my-tools --json
またはファイルを渡す:
claude mcp add my-tools --json < server-spec.json
これは位置指定形式と同等ですが、バージョン管理や共有が可能な単一の設定成果物を提供します。
サーバーの一覧表示と削除
# 登録されたすべてのサーバーを表示
claude mcp list
# サーバーを削除
claude mcp remove my-tools
スコープ: プロジェクト vs ユーザー
デフォルトでは、claude mcp add はユーザーレベルの設定にサーバーを登録し、すべての Claude Code セッションで利用可能にします。現在のプロジェクトのみに登録するには（.claude/settings.json に保存）、--scope project を追加します:
claude mcp add my-tools python /path/to/mcp_server.py --scope project
プロジェクトスコープのサーバーは、異なるプロジェクトで異なるツールが必要で、設定を分離したい場合に便利です。
claude mcp serve — Claude Code を MCP サーバーとして公開する
逆方向も可能です。claude mcp serve は Claude Code 自体を MCP サーバーとして起動し、別の MCP ホストが接続してそのツールを使用できるようにします:
claude mcp serve
これは、別のホストがツール呼び出しを調整する大規模なエージェントパイプラインに Claude Code の機能を組み込みたい場合に便利です。
Claude Desktop の MCP サーバー設定
Claude Desktop は MCP サーバー設定を JSON ファイルに保存します。場所は OS によって異なります:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
ファイルが存在しない場合は作成します。構造は次のようになります:
{
"mcpServers": {
"my-tools": {
"command": "python",
"args": ["/path/to/mcp_server.py"],
"env": {
"API_KEY": "your_key_here"
}
}
}
}
mcpServers の各キーは、Claude が識別に使用するサーバー名です。必要なだけサーバーを登録できます。Claude Desktop は起動時にすべてを読み込みます。
ファイルを編集した後、Claude Desktop を再起動して変更を反映させます。MCP ツールが正常に読み込まれると、チャット入力エリアにハンマーアイコンが表示されます。
SSE 経由でリモート MCP サーバーを追加する
stdio ではなく Server-Sent Events (SSE) トランスポートを使用するリモートサーバーの場合、設定の形状が少し異なります:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse"
}
}
}
一部のリモートサーバーは認証を必要とします。サーバーが期待する場合は、ヘッダーフィールドにベアラートークンを渡します:
{
"mcpServers": {
"remote-tools": {
"url": "https://your-mcp-server.example.com/sse",
"headers": {
"Authorization": "Bearer your_token_here"
}
}
}
}
MCP トランスポートタイプ: stdio と SSE
MCP サーバーは、次の2つのトランスポートメカニズムのいずれかを使用して Claude ホストと通信します:
stdio — サーバーは同じマシン上でサブプロセスとして実行されます。ホストはプロセスを起動し、標準入出力を介して JSON-RPC メッセージを読み書きします。これはローカルサーバーのデフォルトであり、最も簡単にセットアップできます。
SSE (Server-Sent Events) — サーバーはリモートで実行され、HTTP エンドポイントを公開します。ホストは URL に接続し、ツールの応答をストリームとして受信します。これはマシンをまたいで動作し、共有チームインフラストラクチャやホスト型ツールサービスに適した選択肢です。
ほとんどの個人開発者にとって、stdio の方が簡単です。ネットワークが不要で、サーバープロセスが自動的に管理されます。SSE は、チームで単一の MCP サーバーを共有したい場合や、ツール自体を特定のネットワーク環境で実行する必要がある場合に価値があります。
Claude が MCP ツールをどのように推論するか
セッションが開始され MCP サーバーが登録されると、Claude は各サーバーに利用可能なツールを問い合わせます。これにより、ツール名と JSON Schema の説明のリストが生成されます。Claude は推測的にツールを呼び出しません。ツールの説明に基づいて、会話やタスクで必要になった場合にのみツールを呼び出します。
ツール呼び出しのフローは次のように機能します:
- ユーザーがメッセージまたはタスクを送信します。
- Claude は登録されたツールが役立つかどうかを評価します。
- 役立つ場合、Claude は適切な引数でツール呼び出しを構築します。
- MCP ホストが正しいサーバーに呼び出しを送信します。
- サーバーが実行し、結果を返します。
- Claude は結果を推論に組み込み、続行します。
このループは1回のターンで複数回発生する可能性があります。Claude はツール呼び出しを連鎖させ、あるツールの結果を別のツールの引数に使用し、同じセッション内の複数のサーバーにまたがって集約できます。
ツールの説明の質はここで非常に重要です。曖昧な説明は、呼び出しの見逃しや誤った呼び出しにつながります。ツールの機能、引数の意味、戻り値を含む正確な説明により、Claude は推測することなく正確に呼び出しをルーティングできます。
サンドボックスでのツール実行
MCP ツールがコードを実行する場合（Python スクリプト、シェルコマンド、ファイル操作）、ローカルマシンで実行すると分離に関する問題が生じます。ファイルシステムアクセス、プロセス生成、ネットワーク呼び出しを持つツールは、誤動作したり予期しないパスに誘導されたりすると、広範囲に影響を及ぼす可能性があります。
Novita AI Agent Sandbox は、ツール実行用の隔離されたクラウド環境を提供することでこれに対処します。MCP サーバーをローカルで実行する代わりに、サンドボックスインスタンス内にデプロイします。サンドボックスは独自のファイルシステム、ネットワークスコープ、リソース制限を持ちます。エージェントはその境界内でファイルの書き込み、コードの実行、内部 API の呼び出しを、ホストマシンに触れることなく行えます。
サンドボックス内で実行される MCP サーバーは SSE トランスポートを通じてツールを公開し、Claude はリモートで接続します。そのため、Claude から見ると統合は同じです。違いはツールが実際に何で実行されているかだけです。
MCP デプロイメントのための Novita Sandbox の主な特徴:
- 高速起動: インスタンスは約200ms未満で起動し、ツールのラウンドトリップレイテンシを低く抑えます
- 秒単位の課金: アクティブな実行時間のみ支払い、アイドル予約は課金されません
- 分離されたファイルシステム: 各サンドボックスインスタンスは独立したワークスペースを持ち、セッション間のデータ漏洩を防ぎます
- 設定可能なネットワークポリシー: ツールがアクセスできる外部サービスを制御します
Novita Sandbox を使用した MCP サーバーの構築に関するステップバイステップガイドは、Build a Remote Code Execution MCP Server with Novita Sandbox and mcp-use Library を参照してください。
MCP ツール使用推論のための Novita LLM API の使用
Claude の独自モデルはツール使用をネイティブに処理しますが、コスト、レイテンシ、専門化などの理由から、一部の MCP ツール使用推論を別のモデルを通じてルーティングしたい場合があります。Novita LLM API は、関数呼び出しと構造化ツール呼び出しをサポートするモデルにアクセスできる OpenAI 互換のエンドポイントを提供します。
これは、MCP アーキテクチャに2つの方法で適合します:
1. カスタム MCP ホストの背後にある推論モデルとして: 独自の MCP ホスト（Claude Code や Claude Desktop 以外）を構築している場合、Novita LLM API を使用してモデル層を強化できます。ホストはツールリストと会話を Novita API に送信し、モデルはツール呼び出し指示を返し、ホストはそれを MCP サーバーにディスパッチします。
import openai
client = openai.OpenAI(
base_url="https://api.novita.ai/v3/openai",
api_key="your_novita_api_key",
)
response = client.chat.completions.create(
model="meta-llama/llama-3.3-70b-instruct",
messages=[{"role": "user", "content": "List the available tools and run a quick test"}],
tools=[
{
"type": "function",
"function": {
"name": "list_models",
"description": "List all available models from the API.",
"parameters": {"type": "object", "properties": {}},
}
}
],
tool_choice="auto",
)
2. MCP ツール自体の内部の LLM として: MCP ツールは内部で Novita LLM API を使用できます。例えば、要約ツール、分類ツール、コード生成ツールなどです。ツールはエージェントからの入力を受け取り、Novita API を呼び出し、結果を返します。これにより、モデル推論コストをメインのエージェントモデルコストから分離し、各サブタスクに適切なモデルを選択できます。
Novita の API を呼び出す MCP サーバーの構築に関する実践的な例は、How to Build Your First MCP Server with Novita AI を参照してください。
よくある問題と修正
サーバーが Claude Desktop に表示されない
最も一般的な原因は、claude_desktop_config.json の JSON 構文エラーです。保存する前に JSON バリデーターを使用してください。末尾のカンマでもファイルの読み込みが妨げられます。編集後は毎回 Claude Desktop を再起動してください。
claude mcp add コマンドが見つからない
これは、Claude Code がインストールされていないか、PATH に含まれていないことを意味します。npm install -g @anthropic-ai/claude-code で Claude Code をインストールし、claude --version で確認してください。
ツールがリストされているが呼び出されない
Claude はツールが現在のタスクに関連すると判断した場合にのみツールを呼び出します。ツールの説明が曖昧すぎると、Claude はそれらを選択しません。具体的な説明を追加してください: ツールの機能、使用するタイミング、入力と出力の例など。
サーバーが起動後にすぐに終了する
サーバーコマンドが正しいこと、必要な環境変数がすべて設定されていることを確認してください。ターミナルでコマンドを直接実行して実際のエラー出力を確認してください。Claude Code は一部の設定でサブプロセスの stderr を抑制する場合があります。
SSE 接続が拒否された
サーバー URL が Claude を実行しているマシンから到達可能であること、サーバーが期待するポートで実際にリッスンしていること、必要な認証ヘッダーが正しく設定されていることを確認してください。
ツール呼び出しがバリデーションエラーで失敗する
Claude が渡す引数は、ツールが宣言する JSON Schema と一致する必要があります。ツールの inputSchema 定義を確認してください。必須フィールドが欠けていたり、型が一致しない場合、サーバーは呼び出しを拒否します。Claude はスキーマに基づいて引数を構築するため、不完全なスキーマは不完全な呼び出しにつながります。
FAQ
Claude Code は MCP をサポートしていますか？
はい。Claude Code は claude mcp サブコマンドを通じてネイティブの MCP サポートを備えています。claude mcp add でサーバーを登録し、claude mcp list で登録内容を確認し、claude mcp remove で登録解除します。完全なコマンドリファレンスは claude mcp --help を実行してください。
Claude Code に MCP サーバーを追加するにはどうすればよいですか？
stdio サーバーの場合は claude mcp add <name> <command> [args...] を実行し、JSON 仕様を渡す場合は --json を使用します。プロジェクトスコープの登録には --scope project を追加します。追加後、新しい Claude Code セッションを開始すると、ツールがすぐに利用可能になります。
claude mcp serve とは何ですか？
claude mcp serve は Claude Code 自体を MCP サーバーとして実行し、その機能を MCP プロトコルを通じて公開します。別の MCP ホストが Claude Code に接続し、ツールソースとして使用できるようになります。これは、Claude が複数のコンポーネントの1つであるマルチエージェントシステムを構築する際に便利です。
同じ MCP サーバーを Claude Code と Claude Desktop の両方で使用できますか？
はい。サーバー自体はどのホストが接続するかを気にしません。stdio サーバーの場合、Claude Code（claude mcp add 経由）と Claude Desktop（claude_desktop_config.json 経由）の両方が同じコマンドを起動できます。SSE サーバーの場合、URL に到達できる任意のホストが接続できます。
Claude はどの MCP ツールを呼び出すかをどのように判断しますか？
セッション開始時に、Claude は登録されたすべてのサーバーにツールリストを問い合わせます。各ツールには名前と説明があります。タスクを処理する際、Claude は説明が必要なものと一致するかどうかに基づいてツールを選択します。明確なユースケースを持つ適切に記述された説明は正確なツール選択につながり、曖昧な説明は見逃しや誤った呼び出しにつながります。
MCP の stdio と SSE トランスポートの違いは何ですか？
Stdio はサーバーをローカルサブプロセスとして実行し、ホストは stdin/stdout を介して通信します。SSE はリモート HTTP エンドポイントに接続し、応答をストリームとして受信します。Stdio はローカル開発にはより簡単で、SSE はリモート、共有、本番デプロイメントに適しています。
