Claude Codeの.mcp.json完全設定マニュアル

結論

最初にやること：対象範囲と完了条件を決め、下の手順を上から順に進めます。

Claude Codeのproject scopeで共有するMCP設定ファイルは、リポジトリ直下の.mcp.jsonです。

claude_mcp.jsonやClaude Desktop向け設定形式を置いても、Claude Codeのproject MCPとして読み込まれません。

claude mcp add --scope projectで生成し、必要に応じて環境変数展開を追加します。

記述先：指定された設定ファイルへ保存します。

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/docs",
      "headers": {
        "Authorization": "Bearer ${DOCS_MCP_TOKEN}"
      }
    }
  }
}

具体的な手順

1. claude mcp add --scope projectで雛形を生成する

2. リポジトリ直下の.mcp.jsonを確認する

3. secretを固定値で書かず${VAR}を使う

4. JSON schemaとserver仕様を検証する

5. claude mcp listと/mcpで読み込みを確認する

userとlocal scopeの設定は~/.claude.jsonへ保存され、project scopeだけが.mcp.jsonとして共有されます。

設定ファイルをcommitする前にURL、header名、引数、アクセス範囲をレビューします。

実践プロンプト

移行作業をClaudeへ依頼する安全なプロンプトです。

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

リポジトリにある claude_mcp.json を確認してください。
外部接続は行わず、現行のClaude Code project scope用 .mcp.json へ移行する差分だけを提案してください。
資格情報は値を移さず、${ENV_VAR}形式へ置き換えてください。
未使用server、非推奨transport、危険な書き込み権限を指摘してください。
私の承認後にだけファイルを作成してください。

注意点

JSONが正しくても、serverのcommandやURLが誤っていれば接続できないため、構文検証だけで完了としないでください。

stdio設定で相対パスを使うと起動ディレクトリで挙動が変わるため、共有可能なcommandか絶対パスを検討します。

project trustを承認すると.mcp.jsonなどのproject設定が有効になるため、未知のリポジトリでは内容を読んでから信頼してください。