Claude Code MCP設定の追加方法｜.mcp.json雛形と一覧

Claude Code に MCP サーバーを追加する方法は、claude mcp add コマンドを実行するか、プロジェクト直下の .mcp.json に書くかの 2 通りです。 どちらも同じ形式の設定になり、保存先は「スコープ」（local・project・user）で決まります。

この記事は、MCP サーバーをつなぐ側の設定だけに絞っています。そのまま置ける .mcp.json の全文 6 種類と対応するコマンド、サブコマンド・スコープ・transport・環境変数の一覧、つながらない時の切り分け表を、手元で動かした claude mcp の出力と一緒に載せました。

確認環境：Claude Code 2.1.292（Linux x64）、Python 3.11.15。仕様は 2026年10月7日に公式ドキュメント（code.claude.com/docs）を開いて確認しました。確認環境は外向きの通信をプロキシで制限しているため、例示用のリモート URL（mcp.example.com）への接続は「Failed to connect」と表示されます。

Claude Code の MCP 設定 早見表

claude mcp add で追加する

リモートの HTTP サーバー

# 基本形
claude mcp add --transport http docs https://mcp.example.com/mcp

# ヘッダーを付ける（${...} を展開させないようシングルクォートで囲む）
claude mcp add --transport http --scope user docs https://mcp.example.com/mcp \
  --header 'Authorization: Bearer ${DOCS_MCP_TOKEN}'

2 つ目を実行したときの出力です。ヘッダーの値は画面には出ず、~/.claude.json には ${DOCS_MCP_TOKEN} という参照のまま保存されます。

Added HTTP MCP server docs with URL: https://mcp.example.com/mcp to user config
Headers: {
  "Authorization": "[REDACTED]"
}
File modified: /home/dev/home/.claude.json

ローカルの stdio サーバー

-- の左側が Claude Code のオプション、右側がサーバーを起動するコマンドです。-- より後ろは手を加えずにサーバーへ渡されます。

# local スコープ（既定）
claude mcp add echo-local --env ECHO_PREFIX=local: -- python3 tools/echo_mcp.py

# project スコープ（.mcp.json に書かれる）
claude mcp add --transport stdio --scope project echo -- python3 tools/echo_mcp.py

Added stdio MCP server echo-local with command: python3 tools/echo_mcp.py to local config
File modified: /home/dev/home/.claude.json [project: /home/dev/shop-api]
Added stdio MCP server echo with command: python3 tools/echo_mcp.py to project config
File modified: /home/dev/shop-api/.mcp.json

--env（-e）は複数の KEY=value を受け取るオプションなので、直後にサーバー名を置くと名前まで環境変数として読まれます。 次の順番で実行すると、このメッセージが出ました。

$ claude mcp add --transport stdio --env ECHO_PREFIX=local: echo-local -- python3 tools/echo_mcp.py
Invalid environment variable format: echo-local, environment variables should be added as: -e KEY1=value1 -e KEY2=value2

サーバー名を先に書く（claude mcp add echo-local --env ... -- ...）か、--env の後ろに別のオプション（--transport など）を挟むと通ります。

claude mcp add のオプション

claude mcp add --help（2.1.292）に出るオプションです。

サーバー名に使えるのは英数字・ハイフン・アンダースコアです。workspace などの組み込みサーバー名は予約されています。

$ claude mcp add "my server" -- python3 x.py
Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
$ claude mcp add workspace -- python3 x.py
Cannot add MCP server "workspace": this name is reserved.

追加した結果を確かめる

3 つのスコープに 1 つずつ登録した状態で claude mcp list を実行した結果です。

$ claude mcp list
Checking MCP server health…

docs: https://mcp.example.com/mcp (HTTP) - × Failed to connect — ERR_PROXY_TUNNEL: Proxy refused to open a tunnel: 403 Forbidden
echo: python3 tools/echo_mcp.py - √ Connected
echo-local: python3 tools/echo_mcp.py - √ Connected

claude mcp get はスコープ・状態・設定内容と、削除するためのコマンドまで表示します。

$ claude mcp get echo-local
echo-local:
  Scope: Local config (private to you in this project)
  Status: √ Connected
  Type: stdio
  Command: python3
  Args: tools/echo_mcp.py
  Environment:
    ECHO_PREFIX=local:

To remove this server, run: claude mcp remove echo-local -s local

$ claude mcp get docs
docs:
  Scope: User config (available in all your projects)
  Status: × Failed to connect
  Issue: ERR_PROXY_TUNNEL: Proxy refused to open a tunnel: 403 Forbidden
  Type: http
  URL: https://mcp.example.com/mcp
  Headers:
    Authorization: Bearer ${DOCS_MCP_TOKEN}

To remove this server, run: claude mcp remove docs -s user

接続に失敗したときは、list の行末と get の Issue: に理由が付きます。 ${VAR} の参照は展開後の値ではなく名前のまま表示されるので、画面にトークンが出ることはありません。

保存先のファイルはこうなる

project スコープの .mcp.json（コマンドが書き出したもの）です。

{
  "mcpServers": {
    "echo": {
      "type": "stdio",
      "command": "python3",
      "args": [
        "tools/echo_mcp.py"
      ],
      "env": {}
    }
  }
}

local スコープと user スコープは、どちらも ~/.claude.json に入ります。user はトップレベルの mcpServers、local は projects の下のプロジェクトのパスごとに分かれます。

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${DOCS_MCP_TOKEN}"
      }
    }
  },
  "projects": {
    "/home/dev/shop-api": {
      "mcpServers": {
        "echo-local": {
          "type": "stdio",
          "command": "python3",
          "args": [
            "tools/echo_mcp.py"
          ],
          "env": {
            "ECHO_PREFIX": "local:"
          }
        }
      }
    }
  }
}

MCP の「local スコープ」は ~/.claude.json に保存されます。設定ファイルの .claude/settings.local.json とは別の場所なので、名前が似ている点だけ気を付けてください。

そのまま置ける .mcp.json の雛形 6 種

プロジェクト直下に .mcp.json という名前で置きます。6 つとも JSON の構文チェックと claude mcp list での読み込みを通したものです。

1. stdio（ローカルのプロセスを起動する）

{
  "mcpServers": {
    "echo": {
      "type": "stdio",
      "command": "python3",
      "args": ["tools/echo_mcp.py"],
      "env": {
        "ECHO_PREFIX": "[team]"
      }
    }
  }
}

claude mcp add --transport stdio --scope project echo --env 'ECHO_PREFIX=[team]' -- python3 tools/echo_mcp.py

2. http（リモートのサーバーにつなぐ）

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    }
  }
}

claude mcp add --transport http --scope project docs https://mcp.example.com/mcp

3. 環境変数展開（${VAR} と ${VAR:-default}）

端末ごとに違うパスや、リポジトリに入れたくない値を外に出す書き方です。

{
  "mcpServers": {
    "echo": {
      "type": "stdio",
      "command": "${PYTHON_BIN:-python3}",
      "args": ["${CLAUDE_PROJECT_DIR:-.}/tools/echo_mcp.py"],
      "env": {
        "ECHO_PREFIX": "${ECHO_PREFIX:-[team]}"
      }
    },
    "docs": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://mcp.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${DOCS_MCP_TOKEN}"
      }
    }
  }
}

展開されるのは command・args・env・url・headers の 5 か所です。DOCS_MCP_TOKEN を設定しないまま claude mcp list を実行すると、既定値のない変数だけが警告として挙がりました。

docs: ${DOCS_MCP_URL}/mcp (HTTP) - × Failed to connect — ERR_PROXY_TUNNEL: Proxy refused to open a tunnel: 403 Forbidden
echo: ${PYTHON_BIN} ${CLAUDE_PROJECT_DIR}/tools/echo_mcp.py - √ Connected

MCP config diagnostics ‼

For help configuring MCP servers, see: https://code.claude.com/docs/en/mcp

[Contains warnings] Project config (shared via .mcp.json)
Location: /home/dev/p-3-env/.mcp.json
 └ [Warning] [docs] mcpServers.docs: Missing environment variables: DOCS_MCP_TOKEN

DOCS_MCP_TOKEN=... claude mcp list のように値を渡すと、この警告は出なくなりました。echo は既定値（python3 と .）で起動し、Connected になっています。

• CLAUDE_PROJECT_DIR は Claude Code が起動したサーバーの環境に入れる変数です。command や args で参照するときは、${CLAUDE_PROJECT_DIR:-.} のように既定値を付けます。
• リモートサーバーの url と headers では、ANTHROPIC_API_KEY・ANTHROPIC_AUTH_TOKEN・AWS_BEARER_TOKEN_BEDROCK・HTTPS_PROXY・NPM_TOKEN などの認証情報にあたる変数は空として読まれます。サーバーに渡したい値は、DOCS_MCP_TOKEN のような自分で付けた名前の変数に入れます。

4. OAuth（クライアント ID を事前に登録する）

動的クライアント登録に対応していないサーバー向けです。サーバー側の開発者ポータルで OAuth アプリを登録し、リダイレクト URI に http://localhost:8080/callback を指定したうえで使います。

{
  "mcpServers": {
    "tracker": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "your-client-id",
        "callbackPort": 8080,
        "scopes": "issues:read issues:write",
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

コマンドで登録する場合は次のどちらかです。クライアントシークレットは設定ファイルではなく、システムのキーチェーン（macOS）または認証情報ファイルに保存されます。

# オプションで渡す
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  tracker https://mcp.example.com/mcp

# JSON で渡す
claude mcp add-json tracker \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

--client-secret を付けずに add-json で登録し、get で見た結果です。

$ claude mcp add-json tracker '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --scope user
Added http MCP server tracker to user config
$ claude mcp get tracker
tracker:
  Scope: User config (available in all your projects)
  Status: × Failed to connect
  Issue: ERR_PROXY_TUNNEL: Proxy refused to open a tunnel: 403 Forbidden
  Type: http
  URL: https://mcp.example.com/mcp
  OAuth: client_id configured, callback_port 8080

To remove this server, run: claude mcp remove tracker -s user

登録後のサインインは、セッション内の /mcp か、シェルから claude mcp login tracker で行います。claude mcp login tracker --no-browser を使うと、ブラウザを開かずに認可 URL を表示させられます。

5. headersHelper（接続のたびにヘッダーを生成する）

OAuth 以外の方式（短命のトークンや社内 SSO など）で認証するサーバー向けです。指定したコマンドの標準出力を、接続時のヘッダーとして使います。

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headers": {
        "X-Team": "platform"
      },
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

• コマンドは、文字列のキーと値だけの JSON オブジェクトを標準出力に書きます（例：{"Authorization": "Bearer xxxx"}）。
• シェル経由で実行され、10 秒で打ち切られます。接続のたびに実行され、結果はキャッシュされません。
• 同じ名前のヘッダーは、headers の固定値よりヘルパーの出力が優先されます。
• 実行時に CLAUDE_CODE_MCP_SERVER_NAME と CLAUDE_CODE_MCP_SERVER_URL が渡されるので、1 本のスクリプトで複数のサーバーに対応できます。
• .mcp.json と local スコープのヘルパーは、そのフォルダを信頼（trust）してから実行されます。 信頼する前に claude mcp list を実行すると、次の行が出ました。

MCP server 'internal-api': headersHelper not run — this workspace has no persisted trust; accept the trust dialog here once interactively, or set projects["/home/dev/p-5-headers-helper"].hasTrustDialogAccepted in /home/dev/home/.claude.json.

6. timeout と alwaysLoad（サーバーごとの調整）

{
  "mcpServers": {
    "reports": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "timeout": 600000,
      "alwaysLoad": true
    }
  }
}

claude mcp add-json reports '{"type":"http","url":"https://mcp.example.com/mcp","timeout":600000}' --scope project

雛形の構文チェック

6 つのファイルを Python の json で読み込んだ結果です。

import glob
import json

for path in sorted(glob.glob("*.json")):
    with open(path, encoding="utf-8") as f:
        data = json.load(f)
    for name, server in data["mcpServers"].items():
        keys = ",".join(k for k in server if k != "type")
        print(f"OK  {path}: {name} type={server['type']} keys={keys}")

OK  1-stdio.json: echo type=stdio keys=command,args,env
OK  2-http.json: docs type=http keys=url
OK  3-env.json: echo type=stdio keys=command,args,env
OK  3-env.json: docs type=http keys=url,headers
OK  4-oauth.json: tracker type=http keys=url,oauth
OK  5-headers-helper.json: internal-api type=http keys=url,headers,headersHelper
OK  6-timeout.json: reports type=http keys=url,timeout,alwaysLoad

claude mcp のサブコマンド一覧

claude mcp --help（2.1.292）に出る 10 個です。

削除とリセットを実行したときの出力です。存在しない名前を指定すると、登録済みの名前が一覧で返ります。

$ claude mcp remove reports -s project
Removed MCP server reports from project config
File modified: /home/dev/shop-api/.mcp.json
$ claude mcp remove nothing
No MCP server named "nothing". Configured servers: docs, echo, echo-local, events, tracker
$ claude mcp reset-project-choices
Project-scoped (.mcp.json) server approvals and rejections stored for this project have been reset.
1 server (echo) is still approved by other settings and will connect automatically without prompting.

セッションの中では /mcp で、接続状態の確認、OAuth のサインイン、サーバーの一時的な無効化ができます。

transport は 4 種類

WebSocket は add-json で登録します。

$ claude mcp add-json events '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer ${EVENTS_TOKEN}"}}'
Added ws MCP server events to local config

切断時の動きも種類で異なります。リモートのサーバーはセッション中に切れると自動で再接続を試み（最大 5 回、待ち時間は 1 秒から倍々）、stdio のサーバーはローカルのプロセスなので自動では再接続されません。

どのスコープに置くかの判断表

同じ名前のサーバーが複数の場所にあるときは、local → project → user → プラグイン → claude.ai コネクタの順で先にあるものが 1 つだけ使われます。項目ごとに混ざることはなく、選ばれた場所の設定が丸ごと使われます。

.mcp.json のサーバーは承認が要る

.mcp.json はリポジトリから届くファイルなので、対話セッションでは使う前に承認を求められます。承認前に list を実行するとこう表示されます。

echo: python3 tools/echo_mcp.py - ⏸ Pending approval (run `claude` to approve)

• claude を起動して承認するか、自分の ~/.claude/settings.json に "enabledMcpjsonServers": ["echo"] を書くと Connected になります（手元で確認）。
• リポジトリの .claude/settings.json に書いた enabledMcpjsonServers や enableAllProjectMcpServers は、フォルダを信頼するまで使われません。
• disabledMcpjsonServers に書いたサーバーは、どの設定ファイルからでも拒否できます。
• claude -p などの非対話実行では承認の画面を出せないため、project スコープのサーバーは確認なしで読み込まれます。読み込ませたくないものは disabledMcpjsonServers に書きます。

トークンを直書きした例と、環境変数に直した例

直す前：トークンがそのままファイルに入っています。.mcp.json をコミットすると、リポジトリを見られる全員に値が届きます。

{
  "mcpServers": {
    "docs": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer sk-live-0123456789abcdef"
      }
    }
  }
}

直した後：ファイルには変数名だけを書き、値は各自のシェルで設定します。

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

# ~/.zshrc や ~/.bashrc など、各自の環境で設定する
export DOCS_MCP_TOKEN="（発行されたトークン）"

設定し忘れたメンバーには、claude mcp list と claude doctor が変数名を知らせます。claude doctor の出力です。

Invalid settings
- /home/dev/home/.claude.json › mcpServers.docs: Missing environment variables: DOCS_MCP_TOKEN
  Suggested fix: Set the following environment variables: DOCS_MCP_TOKEN

貼り付けたトークンの末尾に改行や空白が入っている場合も、list が場所を知らせます。次は env の値の末尾に空白を入れたときの表示です（値そのものは表示されません）。

 └ [Warning] [echo] mcpServers.echo: Leading or trailing whitespace in: env.ECHO_PREFIX

permissions で MCP ツールを allow / deny する

MCP のツールは mcp__<サーバー名>__<ツール名> という名前で権限ルールに書けます。設定ファイル（.claude/settings.json など）の permissions に入れます。

{
  "permissions": {
    "allow": [
      "mcp__echo__echo",
      "mcp__docs__search_*"
    ],
    "ask": [
      "mcp__tracker"
    ],
    "deny": [
      "mcp__docs__delete_*",
      "mcp__events__*"
    ]
  },
  "enabledMcpjsonServers": ["echo"],
  "disabledMcpjsonServers": ["reports"]
}

• allow でワイルドカードを使えるのは、mcp__<サーバー名>__ まで書いた後ろだけです。allow に mcp__* を書くと読み飛ばされます。
• mcp__docs__search(query:*) のように丸かっこを付けたルールは、設定ファイルでは読み飛ばされます。
• 判定は deny → ask → allow の順です。上の例では docs の delete_ 系は実行されず、search_ 系は確認なし、tracker は毎回確認になります。

このファイルを置いて claude doctor を実行したところ、権限ルールについての指摘は出ませんでした。

MCP 関連の環境変数一覧

ツール出力については、トークン数とは別に、テキストの結果が 50,000 文字を超えるとファイルに保存され、会話にはそのパスが入ります（MAX_MCP_OUTPUT_TOKENS では変わりません）。

MCP 関連の設定キー（settings.json）

つながらない時の切り分け表

まず claude mcp list で状態を見て、気になるサーバーを claude mcp get <名前> で確認します。

同じ名前のサーバーを別のスコープにも登録していて、接続先が違う場合も list と /mcp に警告が出ます。残したいほうを決めて、もう一方を claude mcp remove <名前> --scope <スコープ> で消します。

接続確認に使った最小の stdio サーバー

この記事の echo は、設定の読み込みと接続状態を確かめるために用意した小さなサーバーです。標準ライブラリだけで動きます。tools/echo_mcp.py として保存すれば、上の雛形 1 と 3 をそのまま試せます。

"""接続確認用の最小 stdio MCP サーバー（標準ライブラリのみ）"""
import json
import os
import sys


def send(msg):
    sys.stdout.write(json.dumps(msg, ensure_ascii=False) + "\n")
    sys.stdout.flush()


for line in sys.stdin:
    line = line.strip()
    if not line:
        continue
    req = json.loads(line)
    method, rid = req.get("method"), req.get("id")
    if rid is None:  # 通知には応答しない
        continue
    if method == "initialize":
        result = {
            "protocolVersion": req["params"]["protocolVersion"],
            "capabilities": {"tools": {}},
            "serverInfo": {"name": "echo", "version": "0.1.0"},
        }
    elif method == "tools/list":
        result = {"tools": [{
            "name": "echo",
            "description": "受け取った文字列をそのまま返す",
            "inputSchema": {"type": "object", "properties": {"text": {"type": "string"}}, "required": ["text"]},
        }]}
    elif method == "tools/call":
        text = req["params"]["arguments"]["text"]
        prefix = os.environ.get("ECHO_PREFIX", "")
        result = {"content": [{"type": "text", "text": prefix + text}]}
    elif method == "ping":
        result = {}
    else:
        send({"jsonrpc": "2.0", "id": rid, "error": {"code": -32601, "message": f"unknown method: {method}"}})
        continue
    send({"jsonrpc": "2.0", "id": rid, "result": result})

標準入力に 3 行（initialize・通知・tools/list）を流したときの応答です。

$ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' '{"jsonrpc":"2.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | python3 tools/echo_mcp.py
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2025-06-18", "capabilities": {"tools": {}}, "serverInfo": {"name": "echo", "version": "0.1.0"}}}
{"jsonrpc": "2.0", "id": 2, "result": {"tools": [{"name": "echo", "description": "受け取った文字列をそのまま返す", "inputSchema": {"type": "object", "properties": {"text": {"type": "string"}}, "required": ["text"]}}]}}

よくある質問

Q. claude mcp add と .mcp.json の手書きは、どちらを使えばよいですか？ A. 結果は同じ形式になります。--scope project を付けた add は .mcp.json を作成・更新するので、最初の 1 つはコマンドで作り、oauth や timeout のような細かい項目は手で足す、という進め方が手早いです。

Q. local スコープの設定はどこにありますか？ A. ~/.claude.json の projects の下に、プロジェクトのパスごとに保存されます。プロジェクトのフォルダの中にはファイルができないので、コミットに混ざることはありません。

Q. チームで共有しつつ、トークンは共有したくないときは？ A. .mcp.json には ${DOCS_MCP_TOKEN} のような参照だけを書き、値は各自の環境変数で設定します。未設定の場合は claude mcp list が変数名を警告として表示します。

Q. サーバーを削除せずに一時的に止められますか？ A. セッション内の /mcp でサーバーをオフにできます。選んだ内容はプロジェクトごとに ~/.claude.json へ記録され、設定そのものは残ります。

まとめ

• 追加は claude mcp add（または add-json）か .mcp.json。リモートは --transport http、ローカルは -- コマンド の形。
• スコープは local（既定・自分だけ）／project（.mcp.json で共有）／user（全プロジェクト）。同名は local → project → user の順で 1 つだけ使われる。
• .mcp.json には ${VAR} と ${VAR:-default} が使え、展開されるのは command・args・env・url・headers。
• transport は http・stdio・sse（非推奨）・ws。ws は add-json で登録する。
• --env の直後にサーバー名を置かない。名前を先に書くと確実。
• MCP ツールの権限は mcp__サーバー名__ツール名。allow のワイルドカードはサーバー名の後ろだけ。
• つながらない時は claude mcp list → claude mcp get <名前> → claude doctor の順に見る。

参考・出典

確認日：2026年10月7日

• Claude Code Docs: MCP — https://code.claude.com/docs/en/mcp
• Claude Code Docs: Settings reference（MCP） — https://code.claude.com/docs/en/settings-reference
• Claude Code Docs: Configure permissions — https://code.claude.com/docs/en/permissions
• Claude Code Docs: Environment variables — https://code.claude.com/docs/en/env-vars

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。