こんにちは、Lena です。MCP はもう新しい概念ではありませんが、Claude Code の中で server を実際に繋ぎ込んで、面倒に巻き込まれずに動かすところまで持っていくのは、思っているより細かい話が多いです。
この数か月、私は日々の開発で Claude Code にいろいろな MCP server を繋いで使ってきました——GitHub、Sentry、それから社内 database 用に自前で作った query ツールまで。正直に言うと、接続そのものは難しくありません。難しいのは、何を信用するか、OAuth が壊れたときにどこを見ればいいか、scope が実際にどう動いているのかを把握することです。 この記事は、私がぶつかったハマりどころと、追いかけてきた公式仕様のディテールを煮詰めたもので、すでに Claude Code を使っていて、これから MCP server を繋ごうとしている開発者に向けて書いています。
MCP server を繋ぐ前に確認すべきこと
Claude Code のバージョンとプラットフォーム対応
まずバージョンを見ます。OAuth 関連の挙動が安定したのは v2.1.64 以降——このバージョンで authServerMetadataUrl のサポートが入りました。それより古いバージョンでは、remote server との認証時にエラーになります。Windows には既知のクセもあって、claude mcp add-json で HTTP server を追加すると、たまに "Invalid input" が返ってくることがあります。公式 MCP ドキュメントは、こういう時には claude mcp add --transport http 形式に戻すのを推奨しています。
MCP が Claude Code の中で実際にできること
MCP は Claude Code を、ローカルファイルの読み書きと bash 実行しかできない道具から、外部システムと直接やり取りできる agent へと変えてくれます——Jira チケットを取ってきたり、GitHub の PR を作ったり、Sentry で本番エラーを調べたり、いずれもその範囲です。ただ、よく見落とされがちな点があります:MCP server 同士は完全に隔離されています。 passthrough はなく、それぞれの層は独立しています。
Tools、resources、prompts
MCP の仕様によれば、server は三種類の能力を公開できます——tools(実行可能なアクション)、resources(読み取り可能なデータソース)、prompts(事前定義された対話テンプレート)。/mcp パネルは接続済みの各 server のツール数を表示し、tools capability を宣言しているのに実際には何もツールを公開していない server には印を付けてくれます。
ステップごとに最初の MCP server を追加する
CLI から server を追加する
Claude Code は三つの transport を扱えます——HTTP(リモートサービスにはこれを推奨)、SSE(非推奨、できれば避ける)、stdio(ローカルプロセス)。
# Remote HTTP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Local stdio server
claude mcp add --transport stdio --env API_KEY=your_key myserver \
-- npx -y my-mcp-server
ここで一番つまずきやすいポイント:option はすべて server name の前に書く必要があります。 ダブルハイフン -- は、Claude 側の flag と、MCP server プロセスに渡される引数を分けるためのものです。順番を間違えると、コマンドは黙って失敗します。私自身、一度ならずやられました。
.mcp.json でチーム共有する
--scope project を使うと、設定を .mcp.json ファイルに書き出してバージョン管理に commit できます。実際の token をこのファイルに直接書くのは絶対にダメです——環境変数の参照に置き換えてください。同名 server については local scope が project scope を上書きするので、認証情報をプライベートに保つことができます。
server が本当に繋がっているか確かめる
Claude Code で /mcp を打つと状態とツール数が見えます。v2.1.121 以降、HTTP/SSE server は初回接続を自動で最大 3 回までリトライしますが、認証エラーと 404 はリトライ対象外——こちらは設定変更でないと直りません。
初回呼び出し時の承認
新しい server からツールを最初に呼び出すと、Claude Code は権限の確認を求めます。これは設計上の信頼検証です。Claude Code のセキュリティドキュメントにも明記されています——新しい MCP server はユーザー確認が必須です。一回だけ許可することも、"Always allow" を選んで allowlist に入れることもできます。
認証と OAuth フロー
OAuth トークンが必要な server
ほとんどの remote server——GitHub、Slack、Notion など——は OAuth を要求します。Claude Code は OAuth 2.1 に対応していて、フローはほぼ自動です:server が 401 を返すと、Claude Code はまず RFC 9728 の Protected Resource Metadata を見に行き、見つからなければ RFC 8414 にフォールバックします。Dynamic Client Registration に対応していれば client として自動登録され、ブラウザが立ち上がってユーザーに認可してもらい、最後に token を取得します。
server が Dynamic Client Registration をサポートしていない場合は、"Incompatible auth server" というエラーに出会います。そうなったら server 側の開発者ポータルで OAuth アプリを手動登録し、client ID と secret を取って、--client-id と --client-secret を使って server を追加します。callback ポートを固定で要求してくる server もあるので、その場合は --callback-port を、登録済みの redirect URI と合わせます。
認証情報の保存場所とローテーション
トークンはシステムのセキュアな認証情報ストアに保管されます——macOS なら Keychain、それ以外のプラットフォームでは暗号化された認証情報ファイル。設定ファイルに平文で書かれることは一切ありません。 ローテーションしたい時は、/mcp を開いて該当 server を再認証するだけです。ブラウザが使えない SSH 環境では、Claude Code が "Paste code here" というプロンプトを表示するので、別マシンで認可を済ませて、結果を貼り戻せます。
共有 config に token を漏らさない
ここは率直に書きます——hardcode した token 入りの config を public リポジトリに push してしまうチームを、一度ならず見てきました。認証情報は必ず ${ENV_VAR} 参照で渡してください。 エンタープライズ環境では、管理者が managed-mcp.json を配布し、allowlist と denylist で使用可能な server を制御することもできます。
server を信頼する前に確認すべきセキュリティ境界
MCP server がマシン上で読めるもの
stdio タイプの server は現在のユーザー権限で動きます——ここをきちんと考えていない開発者は意外と多い印象です。理屈の上では、.env、SSH 鍵、AWS 認証情報——あなたのアカウントがアクセスできるあらゆるものを読めます。Claude Code 側にも安全装置はあって、書き込み操作は working directory に制限され、ネットワークリクエストは承認が必要です。Anthropic のエンジニアリングセキュリティブログが sandboxing 機構の詳細を書いていて、ファイルシステム隔離とネットワーク隔離が連携して動いています。社内データでは、sandboxing が権限プロンプトを 84% 削減したとのこと——日常の作業フローでは大きな差です。
何を実行・書き込みできるか
MCP ツールには任意の実行能力を持たせられます。本番 database に繋がった "run SQL" ツールは、本物の本番データに対して実際にクエリを発行します。これは仮定の話ではなく——一つの誤設定されたツールが、稼働中の顧客 database に書き込み権限を持ってしまっていた現場を、私は実際に見たことがあります。どんな server でも、繋ぐ前にどのツールが公開されていて、それぞれが何をできるかを正確に把握しておく必要があります。 自信が持てないものは ask モードに残し、安易に自動承認しないこと。
承認前に行う確認
server を信頼する前、私は普段三つのことをやります:ソースコードを見る(GitHub でメインのエントリーファイルを確認し、実際に何をやっているかを把握する)、メンテナンス状況を評価する(3 日前にリリースされたばかりのパッケージと、2 年間メンテナンスされてきたパッケージ——リスクのレベルがまるで別物)、権限宣言を見る(MCP の認可仕様に従って、server は必要な scope を宣言するべきで——合理的な範囲を超えているものは警戒対象です)。
よくある問題と解決方法
追加したのに server が出てこない
一番よくある原因:scope の間違い。 プロジェクト A のディレクトリで --scope local を使って追加した server は、プロジェクト B に切り替えると見えません。claude mcp list で scope を確認し、どこでも使いたければ --scope user に変更します。もうひとつ注意点——workspace は予約名で、これを server name に使うと skip され、warning が出ます。
ツール呼び出しが黙って失敗する
まず、出力がデフォルトの 10,000 トークン上限を超えていないか確認します。Claude Code は上限超過時に warning を出しますが、見落としやすい。MAX_MCP_OUTPUT_TOKENS=50000 を設定すれば上限を引き上げられます。もうひとつは接続切れの可能性——HTTP/SSE server は exponential backoff で自動再接続します(最大 5 回)が、stdio server は自動では再接続しません。
local と project の設定の衝突
同名 server が local と project の両方の scope に存在するとき、local が project を上書きします。 設計どおりの挙動ですが、知らないと「なぜ .mcp.json の変更が反映されないのか」と悩むことになります。claude mcp get <name> で実際に有効になっている設定を確認しましょう。
毎セッションで権限プロンプトが繰り返される
最初に "Always allow" を選んでいなければ、承認は永続化されません。/permissions で永続的な allowlist を管理してください。Claude Code の GitHub リポジトリに PreToolUse hooks のドキュメントがあり、より細粒度の自動承認ロジックを組めます。
繋がってからの先にある限界
MCP はツールを与えてくれるけれど、うまくいった手順は残してくれない
これが日常的に一番強く感じる限界です。MCP が解いてくれるのは「接続」の問題で——「記憶」の問題は解いてくれません。今日 20 分かけて、database のクエリとレポート生成を組み合わせた workflow を完璧に動くところまで持っていったとして、明日の新しいセッションではそのコンテキストがすべて消えています。どのテーブルをクエリすればいいか、どんな形式で出力するか、どの edge case を扱うかを、また説明し直す必要があります。MCP プロトコルにはセッション永続化の仕組みがありません。あらゆる接続が無状態なのです。これはバグではなく——設計上の境界です。
なぜチームはセッションをまたぎ、マシンをまたいで同じ修正を繰り返すのか
開発者 A が、ある server の正しい使い方を理解し、ある edge case を乗り越え、流れをスムーズに整えたとします。でも、その苦労して得た知識には居場所がありません。一週間後、開発者 B がプロジェクトに参加し、まったく同じ問題にぶつかり、まったく同じ時間をデバッグに費やします。.mcp.json が共有するのは設定だけ——「実際にどう使うか」「前回何が壊れて、どう直したか」は共有しません。CLAUDE.md ファイルはある程度それを緩和しますが、静的で手作業のメンテナンスが要ります。MCP は自分の担当範囲を非常によく仕事していますが、workflow が少し複雑になれば、コンテキストの喪失と経験の繰り返しという問題に、いずれ必ず突き当たります。
FAQ
MCP と plugin は同じものですか?
完全に同じではありません。MCP は AI アプリケーションが外部ツールと通信する方法を定義する、開かれたプロトコル標準です。Plugin は Claude Code の中でもっと上位の概念で、MCP server の設定だけでなく、他の種類の拡張も含めることができます。MCP の最初の発表は Anthropic の公式ニュースページで読めます。
MCP server を使うのに API key は必要?
server によります。ローカルの stdio server はだいたい認証が要りません。remote の HTTP server は通常、認証情報が必要です——Bearer token(--header で渡す)か、OAuth(自動処理)のどちらかです。
チームメイトは私の MCP server を見られる?
--scope project の設定だけが .mcp.json に書き出され、チームに共有されます。local(デフォルト)と user の scope はどちらもプライベートです。
local、project、user の scope の違いは?
local(デフォルト):あなただけ、現在のプロジェクトディレクトリでのみ見える。project:プロジェクトルートの .mcp.json に書き出され、バージョン管理を経由してチーム全体と共有される。user:あなただけ、あなたのマシン上のすべてのプロジェクトで見える。古いバージョンでは local が "project"、user が "global" と呼ばれていた点には注意——名前は途中で変わったので、旧称を使っている古いブログやガイドに惑わされないように。
Claude Code が同じツールについて何度も承認を求めてくるのはなぜ?
新しいセッションは一時的な承認をデフォルトでは引き継ぎません。"Always allow" か /permissions でツールを永続的な allowlist に入れてください。エンタープライズ環境では、managed-settings.json の deny ルールが local の allow ルールを上書きするので、それが原因で繰り返し拒否されることもあります。
Previous Posts:
- MCP 自体について、もっと明確なメンタルモデルが欲しい、なぜそれが AI ツール接続の標準層になりつつあるのかを知りたい——その場合はこちら:What Is MCP AI Tool Connection Standard
- Claude Code の中で実際に MCP を使う予定なら、実践的なセットアップと拡張のガイドが本文の workflow と自然に対応します:Claude Code MCP Setup Extensions Guide
- どの MCP server が日々の開発で実際に役立つのか、デモ映えするだけのものではない——その実戦的な棚卸しはブックマーク対象:Best MCP Servers Real World Usefulness
- MCP が扱うのは接続、Claude Skills が扱うのは再利用可能な行動レイヤー——この開発者リファレンスはスタックのもう一面をさらに細かく解説しています:Claude Code Skills Developer Reference
- 本文で触れた「接続 vs 記憶」の限界は、ローカル永続化と workflow の連続性の問題に直接つながります——ここでより深く論じています:Claude Code Local Skills Memory Persistence




