claude mcp addの正しい構文・scope・確認手順

結論

最初にやること：OSのターミナルでclaude mcp add --transport http notion https://mcp.notion.com/mcpを実行します。

claude mcp addはMCP Serverを手作業のJSON編集なしで登録する正式なCLIです。

HTTP型は名前とURLを渡し、stdio型はサーバー名の後に--を置いて実行コマンドと引数を分離します。

共有設定が必要なときだけ--scope projectを付け、生成された.mcp.jsonをレビューしてコミットします。

実行場所：OSのターミナルで実行します。

# HTTP
# ターミナルで実行：MCPサーバーを登録
claude mcp add --transport http notion https://mcp.notion.com/mcp

# stdio
# ターミナルで実行：MCPサーバーを登録
claude mcp add --transport stdio context7 -- npx -y @upstash/context7-mcp

具体的な手順

複雑なヘッダーやWebSocket設定が必要な場合はclaude mcp add-jsonを使えますが、秘密値をコマンド履歴へ残さない設計が必要です。

1. 資格情報付きの個人設定は既定のlocal scopeにします。

2. 全プロジェクトで使う個人ツールは--scope user、チーム共通URLは--scope projectを選びます。

3. 登録後はlist、get、/mcpの三段階で保存内容・接続・認証を確認します。

実行場所：コメントに従い、ターミナルとClaude Codeの対話画面を使い分けます。

# ターミナルで実行：登録済みMCPサーバーを確認
claude mcp list
# ターミナルで実行：MCP設定を管理
claude mcp get notion
# ターミナルで実行：Claude Codeを起動
claude
# 対話中
# Claude Code起動後の対話画面で実行：MCP接続と認証状態を管理
/mcp

実践プロンプト

追加後の最初の依頼では、サーバーが提供するツール名と権限を説明させてから実行へ進みます。

入力場所：Claude Codeの対話画面へ貼り付けます。

notion MCPの接続状態を確認してください。
利用可能なツールを読み取り系と書き込み系に分類してください。
まだページの作成・更新・削除は実行しないでください。

注意点

同じscopeに同名サーバーがあるとalready existsになるため、claude mcp getで確認してからremove・再追加します。

stdio構文で--を忘れるとClaude Code側のオプションとして解釈され、起動引数が壊れることがあります。

project scopeはURLを共有できますが、APIキーやPATを直書きしてはいけません。

Pending approvalは接続障害ではなく、信頼済みworkspaceで対話起動し、設定内容を承認するまで保留されている状態です。