Claude Code の MCP 設定完全手順：claude mcp add / 削除 / スコープの違いを実際に試した

Claude Code は MCP（Model Context Protocol） を使って、外部のツールやデータにつなげられます。設定自体は claude mcp add の 1 行で済みますが、「どのファイルに書かれたのか」「なぜ Pending approval のままなのか」「接続に失敗したときどこを見るか」でつまずきやすいところです。

この記事では、認証のいらない公式ドキュメントの MCP サーバーと、Python で作った小さな自作サーバーを使って、追加・確認・削除・スコープ変更までを実際に試しました。

検証環境

項目	内容
確認日	2026-10-19
Claude Code	2.1.303（ネイティブ版、Claude Pro でログイン）
OS	Debian GNU/Linux 13（trixie）
自作サーバー	Python 3.13.5、MCP Python SDK（mcp）2.3.0
モデル	使用量を抑えるため --model haiku

MCP まわりは更新が速く、表示や仕様はバージョンで変わります。この記事の内容は上記の環境で確認したものです。

先に結論：スコープと保存先

公式ドキュメントの表と、実際に書き込まれたファイルは一致していました。

スコープ	指定	使えるプロジェクト	保存先（実際に確認）
local（既定）	--scope local または省略	追加したプロジェクトだけ	~/.claude.json の projects["<パス>"].mcpServers
project	--scope project	そのプロジェクト（チームで共有）	プロジェクト直下の .mcp.json
user	--scope user	すべてのプロジェクト	~/.claude.json のトップレベル mcpServers

手順 1：HTTP の MCP サーバーを追加する

まずは認証のいらないサーバーで流れを確認します。公式のクイックスタートでも最初の例に使われている、Claude Code ドキュメントの MCP サーバー（https://code.claude.com/docs/mcp）を追加しました。

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Added ... to local config の後の File modified: 行に、書き込まれたファイルとプロジェクトのパスが表示されます。

書き込まれた内容と接続状態を確認する

jq '.projects["/workspace/mcp-demo"].mcpServers' ~/.claude.json
claude mcp list
claude mcp get claude-code-docs

claude mcp get は、スコープ・状態・接続先に加えて、削除するときのコマンド（-s local 付き）まで表示してくれます。

手順 2：project スコープと user スコープで追加する

同じサーバーを、名前を変えて project スコープと user スコープでも追加しました。

claude mcp add --scope project --transport http docs-team https://code.claude.com/docs/mcp
cat .mcp.json
claude mcp add --scope user --transport http docs-everywhere https://code.claude.com/docs/mcp
jq '.mcpServers' ~/.claude.json

.mcp.json は末尾に改行がない形で書き出されたため、cat の直後にプロンプトがくっついて表示されています。チームで Git 管理するなら、エディタ側で改行が追加されて差分が出ることがあるので覚えておくとよいです。

project スコープは「承認待ち」になる

この状態で一覧を見ると、project スコープの docs-team だけ状態が違います。

.mcp.json はリポジトリに入れて共有するファイルなので、clone しただけで勝手にサーバーが動かないよう、対話モードの claude で承認するまで使われません。ドキュメントの表現では「設定決定を報告する」状態で、接続を試した結果ではありません。

手順 3：対話モードで .mcp.json のサーバーを承認する

プロジェクトで claude を起動すると、フォルダの信頼確認のあとに MCP サーバーの承認ダイアログが出ました。

初期選択が 「Continue without using this MCP server」（使わずに続ける） になっている点に注意してください。Enter を連打すると承認されません。

承認後に /mcp を開くと、スコープごとにサーバーと設定ファイルの場所がまとめて表示されます。

サーバーを選ぶと詳細画面になり、状態や設定ファイルの場所、再接続・無効化のメニューが出ます。

承認はどこに保存されるのか

承認の結果は、~/.claude.json ではなく、プロジェクトの .claude/settings.local.json に書かれていました。

手順 4：自作の stdio MCP サーバーをつなぐ

次は、手元で動くプログラムをサーバーにする stdio 方式です。Python の公式 SDK で、ツールを 2 つだけ持つ最小のサーバーを作りました。

mkdir -p /workspace/mcp-demo && cd /workspace/mcp-demo
python3 -m venv .venv
.venv/bin/pip install mcp

server.py（実際に使ったファイルそのままです）:

"""最小の stdio MCP サーバー（検証用）"""
from datetime import datetime
from zoneinfo import ZoneInfo

from mcp.server import MCPServer

mcp = MCPServer("jptools")


@mcp.tool()
def jst_now() -> str:
    """現在の日本時間（Asia/Tokyo）を返す"""
    return datetime.now(ZoneInfo("Asia/Tokyo")).strftime("%Y-%m-%d %H:%M:%S JST")


@mcp.tool()
def count_chars(text: str) -> dict:
    """文字数・バイト数（UTF-8）・行数を数える"""
    return {
        "chars": len(text),
        "utf8_bytes": len(text.encode("utf-8")),
        "lines": text.count("\n") + 1,
    }


if __name__ == "__main__":
    mcp.run()  # 既定は stdio トランスポート

わざと失敗させてみる

stdio サーバーは -- の後ろに起動コマンドを書きます。最初に、ファイル名を打ち間違えた状態（server.py → sever.py）で登録してみました。

claude mcp add jptools -- /workspace/mcp-demo/.venv/bin/python /workspace/mcp-demo/sever.py
claude mcp get jptools

claude mcp add は設定を書き込むだけなので、コマンドが間違っていても Added と表示されます。claude mcp get の Issue: CONNECTION_CLOSED だけでは原因がわからないので、登録したコマンドをそのまま自分で実行するのが早いです。

Claude から自作ツールを呼ぶ

接続できたら、claude -p から呼んでみます。MCP のツールは mcp__<サーバー名>__<ツール名> という名前になるので、--allowedTools で許可します。

ついでに、手順 1 のドキュメント MCP も使ってみました。公式クイックスタートの例と同じく MCP_TIMEOUT について調べさせています。

手順 5：スコープを変更する・削除する

スコープは追加時に決まり、あとから変更するコマンドはありません。削除して、別のスコープで追加し直すのが公式の手順です。

claude mcp remove claude-code-docs --scope local
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

同じ名前が 2 つのスコープにあるとき

わざと local にも同じ名前で（存在しない URL を）登録して、どちらが使われるかを見ました。

• claude mcp get は local の定義を表示しました。ドキュメントの優先順位（local → project → user → プラグイン → claude.ai コネクタ）どおりです。項目ごとのマージはされず、定義まるごとが使われます。
• スコープを付けずに remove すると、削除せずに -s local / -s user の指定を求めてきました。

なお、example.invalid への接続エラーはこの検証環境では ECONNRESET と表示されました。ネットワーク環境によって表示は変わると思われます（未確認）。

後片付け

削除して気づいたことが 2 つあります。

• project スコープを全部消しても、.mcp.json は {"mcpServers": {}} として残りました。不要ならファイルごと削除します。
• 承認の記録（.claude/settings.local.json の enabledMcpjsonServers）は、サーバーを消しても docs-team が残ったままでした。同じ名前で別の中身のサーバーが後から追加されたときにどう扱われるかは未確認です。気になる場合は手で消すか、claude mcp reset-project-choices を使ってください。

claude mcp list の状態の読み方

今回実際に見た状態と、ドキュメントに載っている状態をまとめます。

表示	意味	対処	確認
✔ Connected	使える	—	実際に表示
⏸ Pending approval	.mcp.json のサーバーが未承認	対話モードの claude で承認	実際に表示
✘ Failed to connect	サーバーが応答しない	コマンド・URL を直接試す	実際に表示
! Needs authentication	ブラウザでのサインインかトークンが必要	/mcp から認証、または --header	claude.ai から同期されたプラグインで表示
! Connected · tools fetch failed	接続できたがツール一覧を取れない	claude mcp get で詳細を見る	ドキュメントのみ（未確認）
⊘ Disabled for this project	プロジェクトで無効化されている	/mcp で有効に戻す	ドキュメントのみ（未確認）

つまずきポイントのチェックリスト

• claude mcp list に知らないサーバーが出る → claude.ai にログインしていると、アカウントのコネクタ（claude.ai ...）や同期されたプラグイン（plugin:...）も並びます。なお、ANTHROPIC_API_KEY を設定していると claude.ai のコネクタは読み込まれない旨の警告が出ました（エラー・利用制限の記事で詳しく扱っています）。
• project スコープのサーバーが使われない → Pending approval になっていないか確認。対話モードで承認します。
• stdio サーバーが Failed to connect → claude mcp get に出るコマンドをそのまま実行する。仮想環境の Python は絶対パスで書くと確実です。
• claude -p でツールが使われない・エラーになる → --allowedTools mcp__サーバー名__ツール名 を付け、プロンプトはオプションより前に書く。
• 起動が遅いサーバーがタイムアウトする → MCP_TIMEOUT（ミリ秒、既定 30000）で延ばせます（ドキュメントの記述。今回は試していません）。

まとめ

MCP サーバーを増やすと、ツール名などがコンテキストに入ります。どれくらい入っているかは /context で確認できます（利用制限の記事で実際の画面を載せています）。決まった手順を Claude に覚えさせたいだけなら、MCP より Skills（SKILL.md） のほうが手軽な場合もあります。設定ファイルの置き場所の考え方は hooks の記事 も参考にしてください。

参考

• MCP サーバーに接続する（公式クイックスタート）
• MCP を介して Claude Code をツールに接続する（公式）
• 環境変数リファレンス（公式）

この記事は、AI を使って下書きを作り、手順とコマンドの出力・画面は筆者の検証環境で実際に実行して確認しています。アイキャッチ画像は生成画像（イラスト）で、実際の画面ではありません。