Claude CodeのMCP設定｜サーバーを追加してつながったか確かめる手順

claude code mcpで調べている人の多くは、サーバーを追加するコマンドは見つけたものの、それが本当に動いているのか、どこに設定が書かれたのかが分からずに止まっている。MCPの追加は1行で終わるが、スコープの選び方と、つながったことの確かめ方を押さえていないと、別のフォルダで開いた途端に使えなくなったり、チームの誰かの環境だけ動かなかったりする。追加、確認、失敗の読み方の3段で整理する。

MCPはClaude Codeに外の道具を渡す仕組み

MCP（Model Context Protocol）は、AIのアプリと外部の道具をつなぐための公開された取り決めだ。Claude Codeは単体でもファイルを読み、コマンドを実行し、コードを書き換えられる。ただ、それだけではブラウザを操作したり、社内のデータベースを引いたり、デザインファイルの中身を読んだりはできない。そこを埋めるのがMCPサーバーで、1つのサーバーが1つの道具の窓口になる。

Claude Codeの公式ドキュメントは、MCPを通じて数百の外部ツールやデータ源につなげると説明している。Notionのように提供元が遠隔のサーバーを公開しているものもあれば、手元のMacで動かすものもある。前者はURLを登録するだけで済み、後者はMacの中でプログラムを起動する形になる。この違いが、後で出てくる接続方式の選び方に直結する。

ここ1年ほどで、MCPはClaude Code専用の仕組みではなくなった。同じサーバーをCursorやGemini CLI、Codex CLIからも使えるため、提供元のセットアップ手順が別のアプリ向けに書かれていることも多い。そのときも、手順の中にあるURL、起動コマンド、JSONの塊のどれかを拾えばClaude Code側の登録に書き直せる。道具ごとに作り直す必要はない。

一方で、つなげる数が増えるほど、どのサーバーがどのフォルダで有効なのかを把握しづらくなる。最初に考えておきたいのは、便利そうなサーバーを並べることではなく、いま手が止まっている作業に対して、どの道具が1つあれば往復が減るのかという点だ。

追加は3つの形のどれかで書く

Claude Codeへの追加は、ターミナルで claude mcp add を実行する。サーバーの種類によって書き方が3つに分かれる。

遠隔のサーバーはURLを渡す

提供元が https:// で始まるURLを公開している場合は、接続方式に http を指定して名前とURLを渡す。公式ドキュメントの例では、Notionを claude mcp add --transport http notion https://mcp.notion.com/mcp で登録している。認証が必要なサーバーは、追加したあとにClaude Codeの中で /mcp を開き、ブラウザでサインインする流れになる。SSEという古い方式しか持たないサーバーもあるが、新しい版のClaude Codeは http で試してだめならSSEへ切り替える。

手元で動かすサーバーは -- の後ろに起動コマンドを置く

npx や uvx で起動するサーバーは、Macの中で動くプログラムとして登録する。ここで迷いやすいのが --（ハイフン2つ）の意味だ。これより前はClaude Code自身への指定、後ろはサーバーを起動するコマンドそのものとして扱われる。-y のようなnpxの指定を -- の前に置くと、Claude Codeが自分への指定だと解釈して失敗する。

claude mcp add playwright --scope project -- npx -y @playwright/mcp@latest Playwright MCPを使うと、Claudeはブラウザのナビゲーションやクリック・フォームへの入力・スクリーンショットの取得・レンダリング結果の確認を実際に行えます。 出典: qiita.com

APIキーのような値は --env KEY=値 で渡す。この指定はサーバー名と -- の間に置く。

他のアプリ向けのJSONは add-json で入れる

Claude Desktopなどの手順に mcpServers というJSONが載っている場合は、その中身を claude mcp add-json 名前 'JSON' で渡す。外側の mcpServers は付けない。URLだけあって type が無い項目は、手元で動くサーバーと誤解されて読み込まれないので、"type": "http" を書き足してから入れる。

スコープの選び方で「別のフォルダで使えない」が起きる

MCPのつまずきで最も多いのが、スコープの取り違えだ。Claude Codeには保存先が3つあり、何も指定しなければローカルになる。

スコープ	使える範囲	チームと共有	保存先
local（既定）	追加したフォルダだけ	しない	~/.claude.json
project	そのフォルダだけ	する	フォルダ直下の .mcp.json
user	すべてのフォルダ	しない	~/.claude.json

「昨日追加したのに、別のフォルダで開いたら出てこない」という相談は、ほぼ既定のローカルで追加しているのが原因だ。ローカルはそのフォルダのパスに結び付けて保存されるので、他のフォルダでは読み込まれない。個人で使う道具を全部の作業で使いたいなら --scope user を付けて追加し直す。

逆に、リポジトリで共有したいサーバーは --scope project にして .mcp.json をコミットする。この場合、他の人が最初に開いたときは承認待ちの状態になり、その人が claude を起動して許可するまでつながらない。複製しただけのリポジトリが自分でサーバーを承認できない作りになっているのは、見知らぬ設定が勝手に動くのを防ぐためだ。

同じ名前のサーバーを複数のスコープに別々の宛先で登録すると、Claude Codeが警告を出す。認証も宛先ごとに保存されるので、片方でサインインしても、別の定義が読み込まれるフォルダでは改めてサインインが要る。使う方を残し、他は claude mcp remove 名前 --scope スコープ で消しておくと混乱が減る。

APIキーを含む設定は、共有のスコープに書かないのが基本になる。.mcp.json をコミットすると鍵まで履歴に残るため、鍵は環境変数で渡し、ファイルには変数名だけを書く形にする。

つながったかを確かめる3つの方法

claude mcp add を実行すると Added ... と表示されるが、これは設定が書き込まれたという意味で、接続できたことの証明ではない。確かめる手は3つある。

1つめは claude mcp list だ。登録したサーバーの一覧の横に、✔ Connected（接続済み）、! Needs authentication（認証待ち）、✘ Failed to connect（接続失敗）のような状態が出る。失敗と出ても一覧のコマンド自体が失敗したわけではなく、そのサーバーにつながらなかったという意味だ。承認前の共有サーバーは ⏸ Pending approval と表示される。

2つめは claude mcp get 名前 で、1台ずつ詳しく見る方法だ。接続に失敗しているときは Issue: の行に、HTTPの状態コードやサーバーが返したエラーの文が出る。鍵に見える文字列は伏せて表示されるので、画面をそのまま人に見せても漏れにくい。

3つめは、Claude Codeの中で /mcp を開く方法だ。サーバーごとの状態と、使える道具の数が並ぶ。OAuthの認証もここから始める。道具の数が0になっているサーバーは、つながっていても実際には何もできない状態なので、ここで気づける。サーバーを消さずに一時的に止めたいときも、この画面で切り替えられる。

実際に使えるかどうかの最後の確認は、Claudeに具体的な作業を頼むことだ。Playwrightなら「このURLを開いて見出しを一覧にして」と頼み、道具の呼び出しが表示されるかを見る。呼ばれずに自分の知識で答え始めたら、サーバーが読み込まれていないか、頼み方が道具の用途と噛み合っていない。

うまくいかないときに見るところ

失敗の原因は、多くの場合次のどれかに当てはまる。

• 起動に時間がかかるサーバーが待ち時間を超えている。環境変数 MCP_TIMEOUT で起動の待ち時間を延ばせる。公式の例では MCP_TIMEOUT=10000 claude で10秒に設定している
• 鍵を貼り付けたときに末尾の改行が混ざっている。Claude Codeは値の前後の空白を検出して警告するが、自動では削らない
• 予約された名前を使っている。workspace や claude-in-chrome などは組み込みのサーバーの名前なので、同じ名前は登録できない
• npxで起動するサーバーで、Node.jsが入っていない、または版が古い

遠隔のサーバーが途中で切れた場合、Claude Codeは自動で接続し直す。対話中なら /mcp に接続待ちとして表示され、5回失敗すると接続失敗の扱いになる。一方、手元で動くサーバーは自動では再接続されないので、/mcp から手で接続し直す。

もう1つ気を付けたいのが、外部の内容を取り込むサーバーの扱いだ。公式ドキュメントは、つなぐ前にそのサーバーを信頼できるか確かめるよう書いている。Webページを読むサーバーは、ページに仕込まれた指示をClaudeが読んでしまう経路にもなる。提供元がはっきりしないサーバーを、鍵を渡した状態で常時有効にしておくのは避けたい。

最初に入れるサーバーの選び方

おすすめのサーバー一覧を眺めて全部入れると、道具の説明だけで作業の文脈が埋まっていく。入れる順番は、いま往復が一番多い作業から決めるのが効率がいい。

• 画面の見た目を確かめる往復が多い人は、ブラウザを操作するPlaywrightから入れる。スクリーンショットを撮って貼る手間が消える
• データを見ながら直す作業が多い人は、データベースのサーバーを検討する。ただし本番の接続先を渡すのではなく、読み取り専用の利用者か手元の複製につなぐ
• デザインから画面を起こす人は、デザインツールのサーバーが候補になる
• 課題管理やドキュメントを参照しながら書く人は、提供元が公開している遠隔のサーバーを使う

比較するときの軸は、そのサーバーが手元で動くか遠隔か、認証が要るか、書き込みができるか、の3つで足りる。書き込みができるサーバーほど便利だが、誤った操作のときの影響も大きい。最初の1週間は読み取りだけの権限で動かし、どの場面で呼ばれるかを見てから書き込みを許すのが安全な進め方だ。

ファイルとターミナルとAIの行き来をどこで減らすか

MCPを整えると、Claude Codeの中でできることは確かに増える。ただ、実際の作業では、Claudeが作ったファイルを確かめるためにFinderを開き、別のフォルダを見にいき、またターミナルに戻るという往復が残る。MCPは道具をClaude側に寄せる仕組みで、人間の側の往復までは減らさない。

この往復を減らす方法として、ファイル管理アプリの中にターミナルとAIを置く形がある。どの操作が1つの窓で完結するのかはできることに整理されている。フォルダとターミナルとAIが同じ窓にあると、Claudeが書き出したファイルを横の一覧でそのまま開いて確かめられる。Finderや他のファイル管理アプリとの違いは他のファイル管理との比較で見比べられる。

MCPサーバーの中には処理に数分かかるものもあり、その間に席を立つこともある。外出先から続きを見る方法はiPhone・iPadから続きをにまとまっている。費用の考え方は料金、細かい疑問はよくある質問で確かめられる。まずは今日いちばん往復した作業を1つ選び、それに合うサーバーを1台だけ、スコープを決めて追加するところから始めると、設定が散らからずに済む。