すべての記事
AFFiNE
Toeverything·公開日 2026年8月19日
ターミナル画面からMCPポートを経てAIアシスタントへつながる図解

Claude CodeにMCPサーバーを追加する方法【設定手順と対処法】

この記事の要点

  • Claude CodeはMCPにネイティブ対応しています。リモートサーバーなら claude mcp add コマンド1回、数分で接続できます。
  • 設定の置き場所は3スコープ(local・project・user)から選びます。チーム共有は project、資格情報は個人スコープが原則です。
  • Claude Desktopは「Connectors(リモート)」と「設定ファイル(ローカル)」の2経路。Claude Codeとは設定が独立しています。
  • サーバーが見えないときは、セッション内の /mcp コマンドで状態を見るのが最短ルートです。

この記事では、claude mcp add の使い方とスコープの考え方、Claude Desktop側の設定、AFFiNEワークスペースを例にした通し手順、そして「つながらない」ときの対処リストまでをまとめます。

Claude CodeにMCPサーバーを追加する

リモート(HTTP)サーバーの場合。ホスト型サービスにつなぐ、いちばん一般的な形です。たとえばNotionの公式サーバーはOAuth認証なので、ヘッダーなしで追加し、セッション内の /mcp からサインインします(手順はNotionをClaude Codeにつなぐ方法を参照)。

claude mcp add --transport http <名前> <サーバーURL> \
  --header "Authorization: Bearer <トークン>"

ローカル(stdio)サーバーの場合。Claude Codeが手元でプログラムを起動します。

claude mcp add <名前> -- <サーバーを起動するコマンド>

管理は3つのサブコマンドで足ります。claude mcp list で一覧、claude mcp get <名前> で詳細、claude mcp remove <名前> で削除。JSON設定を丸ごと登録したいときは claude mcp add-json <名前> '' も使えます。セッション中は /mcp コマンドが接続状態と利用可能なツールを表示します。何かおかしいときは、まずここです。

スコープ: local・project・user

設定がどこに書かれるかで、誰に見えるかが決まります。

  • local(既定): このプロジェクト・このマシン・自分だけ。実験と個人の資格情報向けです。
  • project: リポジトリ直下の .mcp.json に書かれ、バージョン管理でチーム全員に共有されます。ナレッジベースのようにチームで標準にしたいサーバー向け。メンバーには初回に承認プロンプトが出ます。
  • user: そのマシンの全プロジェクトで自分に有効(--scope user)。どこでも使う個人サーバー向けです。

原則はシンプルで、資格情報は個人のスコープに、サーバーの定義だけをprojectスコープで共有し、トークンは各自が環境変数で与える形が安全です。

Claude Desktopに追加する

  • リモートサーバー: 「設定 → Connectors → カスタムコネクタを追加」からURLを貼って認可します。ターミナル不要の経路で、AFFiNEやNotionのようなホスト型サーバーはこちらで足ります。
  • ローカルサーバー: claude_desktop_config.json(設定 → 開発者 → 設定を編集)の mcpServers に追記して、アプリを再起動します。

同じサーバーがClaude CodeでもClaude Desktopでも動きますが、設定はそれぞれ独立です。使うアプリごとに一度ずつ設定してください。

通し実例: 自分のナレッジベースをつなぐ

AFFiNEの内蔵MCPサーバーを例に、最初から最後までの手順です。ワークスペースのドキュメントとホワイトボードが、どのMCPクライアントからでも検索できるようになります。

  1. 資格情報を作る。AFFiNEで「設定 → Integrations → MCP Server → Create credential」。ラベルは「Claude Code」のようにクライアント名にします(1クライアント1本にしておくと失効が楽です)。アクセスは既定の読み取り専用のまま、有効期限を設定します。
  2. 設定をコピーする。トークンは一度だけ表示され、Copy JSONボタンがエンドポイントURLと認証ヘッダー込みの完全な設定を生成します。エンドポイントは https://app.affine.pro/api/workspaces/<ワークスペースID>/mcp という形で、セルフホストなら自分のサーバーのアドレスになります。
  3. 追加する。
claude mcp add --transport http affine \
  "https://app.affine.pro/api/workspaces/<ワークスペースID>/mcp" \
  --header "Authorization: Bearer <トークン>"
  1. 使う。セッションを開いて、自分のノートにしか答えがない質問をします。「決済リトライの設計メモを探して、未解決の論点をまとめて」。Claude Codeが検索ツールを呼び(キーワード+意味検索、ホワイトボードも対象)、権限の範囲で該当ドキュメントの本文を読み、実際のノートの内容にもとづいて答えます。

追加費用はありません。AFFiNE Cloudでも、AI機能を有効にしたセルフホストでも同じように動きます。

ローカルまたはリモートの通信方式を選び、権限を限定した認証情報でMCPサーバーへ接続する流れ
通信方式はサーバーの実行場所を決め、認証情報に付与された権限はクライアントがアクセスできるツールとデータを決めます。

同じ設定をCursorとChatGPTにも使い回す

Cursorは ~/.cursor/mcp.json(プロジェクト単位なら .cursor/mcp.json)を読みます。AFFiNEのCopy JSONの出力は、そのままCursorの形式に一致します。貼って再起動すれば終わりです。

ChatGPTはコネクタ経由でリモートMCPサーバーに対応しており、カスタムサーバーの追加には開発者モード(設定 → コネクタ → 詳細)を使います。同じエンドポイントとヘッダーがそのまま通ります。サーバーは1本、つなぐアシスタントは何台でも。これがMCPの旨みです。

トラブルシューティング: サーバーが見えない

上から順に確認していけば、大半はこのリストの中で解決します。

  • まず /mcp。接続済みか、認証で落ちたか、起動すらしていないかがここで分かります。勘で試す前に、表示されたエラーを読むのが結局いちばん速いです。
  • トランスポート違い。ホスト型サーバーには --transport http が必須です。付け忘れるとURLをローカルコマンドとして扱おうとします。削除して付け直しましょう。
  • ヘッダーの綴り。Authorization: Bearer <トークン> の形です。Bearerの欠落や余分な空白は、静かな401になります。手打ちせずCopy JSONから貼るのが確実です。
  • 資格情報の期限切れ・失効。有効期限付きのトークンは、いつか期限を迎えます。新しい資格情報を発行して登録し直します。
  • スコープの取り違え。localスコープで追加したサーバーは他のプロジェクトには存在しません。期待している場所で claude mcp list を実行すると事実が分かります。
  • ローカルサーバーの依存不足。stdioサーバーはコマンドを起動します。ランタイムが無ければその場で落ちます。まず手でそのコマンドを実行して、生のエラーを見てください。
  • つながるのに使われない。最初の数回は「AFFiNEのワークスペースで〜を探して」のように出どころを明示しましょう。数回やって流れができれば、以降は明示しなくても適切なツールが選ばれやすくなります。

セキュリティの既定値は守る

  • 必要になるまで読み取り専用。ナレッジベース接続に書き込みが要る場面はまれです。AFFiNEの資格情報は既定で読み取り専用、書き込みは段階的に提供中です。
  • 1クライアント1資格情報。ノートPC分だけを失効させても、デスクトップ側が道連れにならないようにするためです。有効期限を付けておけば、更新はただの定例作業になります。セキュリティは退屈なくらいでちょうどいいのです。
  • ツール承認は意識して押す。Claudeは新しいツールの使用前に確認します。projectスコープの共有サーバーも初回承認制です。データを変更しうるものについて、この確認は切らないでください。

よくある質問

Claude CodeにMCPサーバーを追加するコマンドは?

claude mcp add です。ホスト型なら --transport http にサーバーURLと認証ヘッダーを添え、ローカル型なら起動コマンドを渡します。確認は claude mcp list、セッション中の状態確認は /mcp コマンドが最短です。

Claude DesktopはMCPに対応していますか?

対応しています。リモートサーバーは設定のConnectorsからカスタムコネクタとして追加し、ローカルサーバーは claude_desktop_config.json の mcpServers に記述して再起動します。Claude Codeとは設定が別管理な点だけ注意してください。

local・project・userスコープの違いは?

localは1プロジェクト・自分だけ、projectはリポジトリの .mcp.json でチーム共有、userはそのマシンの全プロジェクトで自分に有効です。資格情報は個人側に置き、サーバー定義の共有はprojectスコープで行うのが原則です。

Claude Codeはリモートのサーバーにつなげますか?

つなげます。Streamable HTTPのリモートサーバーは --transport http と認証ヘッダー付きで正式サポートです。AFFiNEのワークスペースエンドポイントのようなホスト型は、ローカルにプロセスを持たずに接続できます。

サーバーが一覧に出てこないのはなぜですか?

/mcp で状態を確認してから、定番の原因を順に見ます。リモートなのに --transport http が無い、Authorizationヘッダーの形式ミス、資格情報の期限切れ、そしてスコープ違い(localで追加すると他プロジェクトには出ません)。この4つで大半が説明できます。

ClaudeでMCPを使うのは無料ですか?

MCP対応自体はClaude CodeにもClaude Desktopにも追加料金なしで入っています。プロトコルもオープンソースです。個々のサーバーの利用条件はそれぞれですが、たとえばAFFiNEの内蔵サーバーはAFFiNE CloudでもAI機能を有効にしたセルフホストでも追加費用なしで使えます。

まとめ

1本つなげば、2本目からは手が覚えています。基本の手順はどのサーバーでも使い回せるからです。最初の1本は、あなたが一日じゅう答えを探している場所——自分のワークスペース——から始めるのが一番割に合います。