mcp-management

MCP サーバー管理

プロジェクトごとに Model Context Protocol（MCP）サーバーを管理するための専門知識です。ランタイム管理、OAuth リモートサーバー、動的なサーバー検出に対応しています。

サーバー設定の例、OAuth の詳細解説、動的検出の詳細、トラブルシューティング用スクリプト、設定パターンの完全な例については、 REFERENCE.md を参照してください。

このスキルを使用する場面

次の場合はこのスキルを使用します…	次の場合は configure-mcp を使用します…
MCP のアーキテクチャと概念を理解する	新しいプロジェクト用に .mcp.json を設定する
ランタイムでサーバーを管理する（有効化／無効化）	新しいサーバーを対話形式でインストールする
OAuth リモート MCP サーバーを設定する	MCP 設定のコンプライアンスチェックを実行する
接続失敗のトラブルシューティングを行う	レジストリから特定のサーバーを追加する
list_changed による動的検出を実装する	プロジェクト標準レポートを生成する

MCP アーキテクチャの概要

MCP は、2 種類のトランスポートを介して Claude Code を外部ツールやデータソースに接続します。

トランスポート	用途	認証	設定
Stdio（ローカル）	npx、bunx、uvx、go run を使ったコマンドベースのサーバー	不要	.mcp.json
HTTP+SSE（リモート）	外部でホストされる URL ベースのサーバー	OAuth 2.1	url フィールドを含む .mcp.json

ローカルサーバーでは command と args を指定し、リモートサーバーでは url と headers を指定します（${VAR_NAME} によるトークン参照を使用し、ハードコードはしません）。詳しくは REFERENCE.md → サーバー設定の例を参照してください。

ランタイムでのサーバー管理

/mcp コマンド（Claude Code 2.1.50+）

設定ファイルを編集せずにサーバーを管理できます。

コマンド	説明
/mcp	設定済みのすべての MCP サーバーと接続状態を一覧表示します
/mcp enable <server>	現在のセッションでサーバーを有効にします
/mcp disable <server>	現在のセッションでサーバーを無効にします（セッション内のみ）

注：有効化／無効化はセッション内のみ適用されます。永続的な変更には .mcp.json を編集してください。

サーバーの状態を確認する

jq -r '.mcpServers | keys[]' .mcp.json   # List configured servers
jq '.mcpServers.context7' .mcp.json      # Verify a server's config

OAuth リモートサーバー（2.1.50+）

リモート HTTP+SSE サーバーは OAuth 2.1 を使用します。Claude Code は /.well-known/oauth-authorization-server からメタデータを検出し（URL ごとにキャッシュされます）、ユーザーは ブラウザーで一度だけ認可します。また、ツールにより高い権限のスコープが必要な場合は、ステップアップ認証によって再認証を求められます。古くなった OAuth 設定を更新するには、サーバーに対して /mcp disable の後に /mcp enable を実行してください。 フロー全体、ステップアップの詳細、キャッシュの動作については、 REFERENCE.md → OAuth サポートを参照してください。

動的なツール検出（list_changed）

{"tools": {"listChanged": true}} を宣言するサーバーは、ツールセットが変わると notifications/tools/list_changed を送信し、Claude Code はセッションを再起動せずにそのサーバーのツールを更新します。プロジェクトのコンテキストに応じたツールを公開するサーバーに便利です。 resources と prompts についても同じパターンが適用されます。サブスクリプションは自動で行われるため、クライアントの設定は不要です。詳しくは REFERENCE.md → 動的なツール検出を参照してください。

トラブルシューティング

一般的な障害の種類と、それぞれに対応する診断スクリプト（サーバーに接続できない、環境変数が不足している、OAuth の問題、SDK MCP の競合状態）については、 REFERENCE.md → トラブルシューティング用スクリプトを参照してください。 OAuth の簡易診断：

症状	考えられる原因	対処方法
認可プロンプトが繰り返し表示される	トークンが保存されていない	トークン保存のアクセス許可を確認する
ステップアップ認証が繰り返される	スコープの不一致	取り消して再認可する
検出に失敗する	サーバーが停止しているか、URL が誤っている	サーバー URL と接続状態を確認する
キャッシュが古い	サーバーの OAuth 設定が変更された	サーバーを無効化してから有効化し、更新する

設定パターン

3 つのスコープそれぞれについて、.mcp.json／settings.json／plugin.json を使った具体例を REFERENCE.md → 設定パターン に記載しています。

• プロジェクトスコープ（推奨）— プロジェクトのルートに .mcp.json を配置します。個人用の設定なら .gitignore に追加し、チーム用の設定なら追跡対象にします。
• ユーザースコープ（個人用）— どこでも利用できるサーバーには ~/.claude/settings.json を使用します。
• プラグインスコープ — plugin.json で宣言します（または "mcpServers": "./.mcp.json" で参照します）。

追加後の承認ゲート（プロジェクトスコープ）

新しく追加したプロジェクトの .mcp.json サーバーは、現在のセッションでそのツールを呼び出せるようになる前に、一度だけユーザーの承認が必要です。これは想定どおりの動作であり、エラーではありません。設定を書き込んだ直後、claude mcp list ではサーバーが ⏸ Pending approval (run 'claude' to approve) と表示され、ユーザーが /mcp コマンドで承認するか、CLI セッションを再起動するまで呼び出せません。いずれもエージェントが代わりに実行できないユーザー専用の操作です。そのため、プロジェクトの .mcp.json にエントリを書き込んだら、ステータス確認でゲートに気づいて途中で尋ねるのではなく、新しいサーバーのツールを利用可能にするには一度だけ承認（/mcp またはセッションの再起動）が必要であることを、あらかじめユーザーに伝えてください。

エージェント向け最適化

コンテキスト	コマンド
ステータスを簡易確認	jq -c '.mcpServers | keys' .mcp.json 2>/dev/null
JSON を検証	jq empty .mcp.json 2>&1
必要な環境変数を一覧表示	jq -r '.mcpServers[] | .env // {} | keys[]' .mcp.json 2>/dev/null | sort -u
特定のサーバーを確認	jq -e '.mcpServers.context7' .mcp.json >/dev/null 2>&1 && echo "installed"
プラグイン内のサーバーを検索	find . -name '.mcp.json' -maxdepth 2

クイックリファレンス

トランスポート別のサーバータイプ

タイプ	使用する場面	例
command（stdio）	認証不要のローカルツール	bunx、npx、uvx、go run
url（HTTP+SSE）	OAuth が必要なリモートホスト型サーバー	https://...

主なファイル

ファイル	用途
.mcp.json	プロジェクトレベルの MCP サーバー設定（チームで共有可能）
~/.claude/settings.json	ユーザーレベルの MCP サーバー設定（個人用）
plugin.json	プラグインレベルの MCP サーバー宣言