mcp-management

MCP サーバーの管理

重要：MCP サーバーを追加、削除、または更新した後は、変更を反映するため、対象のエージェントを再起動するようユーザーに伝えてください。

必須：サーバーを削除する前に、AskUserQuestion を使用してユーザーに確認してください。

クイックリファレンス（Claude Code）

# Install
claude mcp add --transport http <name> <url>
claude mcp add --transport stdio <name> -- <command> [args...]
claude mcp add-json <name> '<json>'              # Full JSON config in one shot

# List/inspect
claude mcp list
claude mcp get <name>

# Remove (confirm with user first!)
claude mcp remove <name>

# OAuth login/logout (for OAuth-protected HTTP servers)
claude mcp login <name>
claude mcp logout <name>

オプションはサーバー名より前に指定する必要があります。2026-04 時点では、--transport http（Streamable HTTP）が推奨されており、sse はサポート終了となっています。

プラグインの MCP サーバーはセッション開始時に自動的に接続されます。セッション中にプラグインを有効化または無効化した後、再初期化するには /reload-plugins を使用してください。

複数のエージェントへのインストール（npx add-mcp）

add-mcp を使用すると、複数のコーディングエージェントに MCP サーバーを一度にインストールできます。

# Remote server (HTTP)
npx add-mcp https://mcp.example.com/mcp

# npm package (stdio)
npx add-mcp @modelcontextprotocol/server-postgres

# Local command
npx add-mcp "npx -y @org/mcp-server --flag value"

# SSE transport
npx add-mcp https://mcp.example.com/sse --transport sse

オプション

フラグ	説明
-g, --global	プロジェクト単位ではなく、グローバルにインストールします
-a, --agent <agent>	対象のエージェントを指定します。複数回指定できます
-n, --name <name>	カスタムサーバー名
-t, --transport <type>	HTTP（デフォルト）または SSE
--header <header>	カスタム HTTP ヘッダー。複数回指定できます
-y, --yes	確認プロンプトをスキップします
--all	検出されたすべてのエージェントにインストールします

対応エージェント

エージェント	CLI 引数	プロジェクト単位に対応
Claude Code	claude-code	はい（.mcp.json）
Claude Desktop	claude-desktop	いいえ（グローバルのみ）
Cursor	cursor	はい（.cursor/mcp.json）
VS Code	vscode	はい（.vscode/mcp.json）
Gemini CLI	gemini-cli	はい（.gemini/settings.json）
Codex	codex	はい（信頼済みプロジェクトのみ、.codex/config.toml）
Goose	goose	いいえ（グローバルのみ）
GitHub Copilot CLI	github-copilot-cli	はい（.vscode/mcp.json）
OpenCode	opencode	はい（opencode.json）
Zed	zed	はい（.zed/settings.json）

Codex App / Desktop の注意事項

Codex には、関連するインターフェースが 2 つあります。

• Codex CLI（codex mcp list、codex mcp get、codex mcp login）では、CLI プロセスから MCP 設定を確認および検証できます。
• Codex App / Desktop のスレッドで MCP ツールを利用できるのは、アプリがサーバーを読み込み、認証した状態でスレッドを開始した場合のみです。サーバーが codex mcp list に表示されていても、サーバーの追加、認証、再読み込みより前にスレッドが作成されていると、現在のモデルターンのツール一覧には表示されないことがあります。

Codex App 用に MCP を設定する場合：

1. ユーザーがリポジトリ単位の設定を明示的に求めている場合は、プロジェクトレベルの .codex/config.toml を優先します。プロジェクトは ~/.codex/config.toml の [projects."/absolute/path"] trust_level = "trusted" で信頼済みに設定する必要があります。
2. OAuth を使用する HTTP サーバーでは、次を実行します。

   codex mcp login <server-name>
   

   次に、codex mcp list に Auth: OAuth と表示されることを確認します。
3. ベアラートークンを使用する HTTP サーバーでは、ヘッダーを直接ハードコードするのではなく、Codex のネイティブなベアラートークン用環境変数形式を優先します。

   codex mcp add <name> --url https://example.com/mcp --bearer-token-env-var EXAMPLE_API_KEY
   

   .codex/config.toml を直接記述する場合は、次の形式にします。

   [mcp_servers.example]
   type = "http"
   url = "https://example.com/mcp"
   bearer_token_env_var = "EXAMPLE_API_KEY"
   

   サードパーティ製のインストーラーの中には、http_headers.Authorization = "Bearer ${EXAMPLE_API_KEY}" と記述するものがあります。Codex CLI ではベアラートークンを使用するサーバーとして表示されることがありますが、ネイティブのフィールドを使うほうが明確です。
4. Codex App の MCP サーバーを追加、削除、編集、またはログインした後は、Codex App を完全に再起動するようユーザーに伝えてください。アプリを再起動すると、既存のスレッドでも新たに利用可能になったツールを使える場合があります。既存のスレッドで tool_search を使ってもサーバーのツールが見つからない場合に限り、フォールバックとして新しいスレッドを作成してください。
5. 検証には 2 つのレベルがあります。

   codex mcp list
   codex mcp get <server-name>
   

   これは Codex CLI、設定、認証を確認します。Codex App のスレッド内では、tool_search を使ってサーバー固有のツール名（例：supabase execute_sql、render list_services）も検索してください。codex mcp list が正しいのに tool_search でツールが見つからない場合、通常は App／スレッドの再読み込みが必要か、App が読み込んでいないスコープにのみサーバーが設定されています。
6. プロジェクトレベルの .codex/config.toml が Codex App に読み込まれない場合は、一時的な診断として、ユーザーレベルの ~/.codex/config.toml にも同じサーバー設定を記述し、App を再起動してツールが表示されることを確認します。ユーザーがリポジトリのみの設定を希望していた場合は、その後、ユーザーレベルの重複設定を削除してください。

例

# Install to Claude Code and Cursor only
npx add-mcp -a claude-code -a cursor https://mcp.stripe.com

# Install npm package to all agents, globally
npx add-mcp -g --all @modelcontextprotocol/server-postgres

# Install with custom name and headers
npx add-mcp -n my-api --header "Authorization: Bearer TOKEN" https://api.example.com/mcp

# List available agents
npx add-mcp list-agents

エージェント固有の設定パス、形式、変換については、references/multi-agent.md を参照してください。

MCP サーバーの検索

MCP サーバーの検索またはインストールをユーザーから依頼された場合は、以下を参照してください。references/search.md：

• 公式ベンダーのサーバー検索（必ず最初に試してください）
• MCP Registry API のクエリ（フォールバック）
• 既知の公式サーバー一覧
• ユーザーの選択用テンプレート形式

信頼性の優先順位：公式ベンダー ＞ MCP リファレンスサーバー ＞ 検証済みパートナー ＞ コミュニティ

サーバーの追加（Claude Code）

環境変数を使用する場合

--env CLI フラグは、特殊文字が含まれると正常に動作しません。代わりに次の手順を行います。

1. 環境変数を指定せずにサーバーを追加します。

   claude mcp add --transport stdio <name> -- npx -y @package/mcp-server
   

2. 設定ファイルを編集して環境変数を追加します。ファイルの場所については、references/scopes.md を参照してください。

最初に設定情報を確認する

インストールの前に、サーバーで API キーやトークンが必要か確認してください。インストールコマンドを実行する前に、AskUserQuestion を使って必要な値を収集します。

サーバーの更新

直接更新するコマンドはありません。次の方法があります。

1. 設定を直接編集する（認証情報の変更に推奨）
2. 削除して再追加する（最初にユーザーに削除の確認を取る）
3. 頻繁に変更される認証情報には環境変数を使用する

OAuth サーバー（GitHub、Sentry）の場合：Claude Code で /mcp を実行して再認証します。

サーバーの削除

削除する前に、必ず AskUserQuestion を使ってユーザーに確認してください。

claude mcp remove <server-name>

プロジェクトスコープのサーバーが .mcp.json に設定されている場合は、ユーザーの確認後にファイルからエントリーを削除してください。

OpenCode 固有の注意事項

OpenCode（anomalyco/opencode v1.14.x）の場合：

• トップレベルのキーは mcp です（mcpServers ではありません）。各サーバーには type: "local" または type: "remote" を必ず指定してください
• ローカルサーバーでは、command は ["bin", "arg1", "arg2"] のような単一の配列です。個別の args フィールドはありません
• 環境変数は environment の下に指定します（env ではありません）
• サーバーごとに enabled: false を指定すると、削除せずに無効化できます
• OAuth サーバー（GitHub など）には opencode mcp auth <name> / opencode mcp logout <name> を使用してください
• v1.14.x では、プラグインの tool.execute.* フックは MCP ツール呼び出しに対して実行されません。代わりに permission ルールを使用してください

OpenCode MCP の詳細なリファレンスについては、references/opencode-mcp.md を参照してください。

リファレンス

• 検索と既知のサーバー：references/search.md
• 複数エージェントへのインストール：references/multi-agent.md
• OpenCode MCP：references/opencode-mcp.md
• トランスポートの種類：references/transports.md
• スコープと設定ファイル：references/scopes.md
• トラブルシューティング：references/troubleshooting.md

スコープの概要（Claude Code）

スコープ	フラグ	設定場所	用途
ローカル	--scope local（デフォルト）	~/.claude.json	個人用開発サーバー
プロジェクト	--scope project	.mcp.json	チームで共有するサーバー
ユーザー	--scope user	~/.claude.json	プロジェクト横断で使うツール

環境変数の構文

設定ファイルでは、${VAR} または ${VAR:-default} を使用します。

Windows に関する注意

npx には cmd /c ラッパーを使用してください：

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package