Claude CodeとCursorのMCP：仕組みと設定方法

要点

MCP（Model Context Protocol）は、AIエージェントを外部のツールやデータにつなぐオープンな標準です。すでにClaude CodeやCursorでコードを書いていて、チャットに貼り付けたテキストを受け取らせる代わりに、エージェントに実際のシステムを照会させたい人に役立ちます。公式ドキュメントはMCPを「an open-source standard for connecting AI applications to external systems」と説明し、USB-Cポートのたとえを使っています。コネクタはひとつ、つながる機器はたくさん、ということです。実際には、設定全体が2つのJSONファイルに収まります。Cursorでは .cursor/mcp.json、Claude Codeでは .mcp.json です。エージェントはこのファイルを読み、サーバーを起動し、公開されたツールが見えるようになります。初めて使うときの問題は、ほぼすべて同じところで起きます。コマンドがエディタのPATHにない、またはNodeのバージョンが古すぎるために、ローカルのサーバーが起動しないのです。以下では、Shopify Dev MCPを例に2つの設定を示し、ファイルのエラーと環境のエラーを切り分けます。

1. MCPとは何か、3つの層で理解する

プロトコルのアーキテクチャに関するドキュメントは、テーマをいくつかの部分に分けています。どのエラーもそのどれかで起きるので、覚えておく価値があります。

参加者。 ホスト（Claude CodeやCursorのようなAIアプリケーション）、クライアント（サーバーごとの専用接続）、サーバー（コンテキストとツールを提供するプログラム）があります。ホストは設定されたサーバーごとにクライアントをひとつ開きます。だから、壊れたサーバーがひとつあっても、ほかのサーバーは巻き込まれません。

データ層。 JSON-RPC 2.0をベースにしたプロトコルです。ここにサーバーのプリミティブがあります。tools（実行可能な関数）、resources（データソース）、prompts（対話のテンプレート）です。クライアントは一覧取得の呼び出しで何があるかを知り、tools/call で実行します。

トランスポート層。 メッセージがどこを通るかを決めます。トランスポートは2つあります。同じマシン上のプロセス間で標準入出力を使うstdioと、POSTを使い、Server-Sent Eventsを任意で併用し、ベアラートークン、APIキー、ヘッダーを受け付けるStreamable HTTPです。トークンを取得する方法として公式に推奨されているのはOAuthです。

プロトコルは日付でバージョン管理されています。現在のバージョンは 2026-07-28 で、番号が変わるのは互換性が壊れるときだけです。ネゴシエーションはリクエストごとに行われ、サーバーは対応していないバージョンを拒否します。

2. 2つのトランスポートと使い分け

トランスポートによって、コードがどこで動くか、インフラの費用を誰が払うか、どう認証するかが決まります。Cursorはこの比較を次のようにまとめています。

出典：Cursor Docs、Model Context Protocol (MCP) のページ、2026年9月21日確認。

実践的なルール：あなたのディスク、ローカルのデータベース、自作のスクリプトに触れるツールならstdio。クラウド上のサードパーティのサービスやチームで使うならHTTP。ひとつのサーバーが複数のクライアントに対応でき、認証もマシンごとに散らばった環境変数ではなくOAuthで行えるからです。

Claude CodeはHTTPをリモートサーバー向けの推奨オプションとし、SSEを非推奨のトランスポートとしています。SSEしか公開していないサーバーも動き続けます。最近のバージョンはまずHTTPを試し、サーバーが受け付けなければSSEに切り替えます。

3. 設定が本当に置かれている場所

マーケットプレイスのインストールボタンは便利機能にすぎません。決め手はファイルです。エージェントがどのファイルを読んだかがわかれば、問題の半分は解決します。

Cursor

置き場所は2つで、違いは適用範囲です。

• プロジェクトルートの .cursor/mcp.json：そのプロジェクトだけに適用されます。
• ホームディレクトリの ~/.cursor/mcp.json：すべてのプロジェクトに適用されます。

Cursorのstdioサーバーは、type、command、args、env、envFile のフィールドを使います。ドキュメントは command について明確に書いています。「must be available on your system path or contain its full path」。この一文を覚えておいてください。セクション5のエラーの原因がこれです。envFile はstdioにしかありません。

Claude Code

スコープは3つあり、それぞれ保存先が違います。

出典：Claude Codeのドキュメント、MCPのページ、2026年9月21日確認。

コミットするファイルは .mcp.json です。Cursorと同じ mcpServers キーを使うので、たいていの場合はブロックをそのまま一方から他方へコピーできます。安全のため、Claude Codeは .mcp.json から来たサーバーを使う前に対話的な承認を求めます。クローンしたリポジトリが勝手にサーバーを起動することはありません。

同じ名前が複数のスコープにある場合、Claude Codeは優先順位の最も高い定義で一度だけ接続し、フィールドを混ぜることはしません。順序はlocal、project、user、プラグインのサーバー、コネクタです。

4. 実践での設定：2つのエディタで同じサーバーを使う

例にはShopify Dev MCPを使います。エージェントに開発者向けドキュメント、APIスキーマ、GraphQL、Liquid、拡張機能の検証へのアクセスを与える公式サーバーです。ローカルでstdioを使って動き、認証を必要としないので、例として適しています。

ファイルを触る前の前提条件

Shopify AI ToolkitにはNode.js 18以上が必要です。エディタを起動するのと同じシェルでバージョンを確認します。

node -v
npx -y @shopify/dev-mcp@latest --help

2つ目のコマンドが応答しないなら、問題はJSONではなく環境です。設定を編集する前に、ここで解決してください。

Claude Code

ドキュメントに載っている方法はCLIを使うもので、設定はCLIが書いてくれます。

claude mcp add --transport stdio shopify-dev-mcp \
  -- npx -y @shopify/dev-mcp@latest

-- は、Claude Codeのオプションと、サーバーを起動するコマンドとを区切ります。これがないと、CLIは -y のようなサーバーのフラグを自分のものとして読んでしまいます。チームと共有するには --scope project を加えます。これで .mcp.json に保存されます。

プロジェクトルートに手で書きたい場合、できあがるファイルは次のとおりです。

{
  "mcpServers": {
    "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] }
  }
}

そのあと、新しい設定を読み込むためにClaude Codeを再起動します。セッション内で /mcp を使うと、サーバーごとのステータスとツール数を示すパネルが表示されます。

Cursor

同じブロックを、プロジェクトルートの .cursor/mcp.json に書きます。

{
  "mcpServers": {
    "shopify-dev-mcp": { "command": "npx", "args": ["-y", "@shopify/dev-mcp@latest"] }
  }
}

保存してCursorを再起動します。Windowsで接続エラーが出る場合の代替手段が、Shopifyのドキュメントに記載されています。command を cmd に変え、args に ["/k", "npx", "-y", "@shopify/dev-mcp@latest"] を渡す方法です。

確認

Claude Codeでは、claude mcp list が各サーバーのステータスを表示します。接続済み、認証が必要、接続失敗のいずれかです。Cursorでは、サーバーはチャットのツールパネルに表示され、ログはOutputのMCP Logsにあります。

5. 定番のエラー：起動しないstdioサーバー

リモートサーバーはHTTPステータスで失敗するので、原因が読み取れます。stdioサーバーは黙って失敗し、その理由はほぼ必ず次のどれかです。

ターミナルで見ているものと違うPATH

stdioサーバーはエディタが起動するプロセスで、あなたのターミナルではなくエディタの環境を引き継ぎます。nvm、asdf、Volta、HomebrewでNodeをインストールし、デスクトップのアイコンからエディタを開いた場合、ターミナルでは動く npx が、エディタからは存在しないことがあります。Cursorのドキュメントが、command はシステムのPATHにあるか、フルパスで指定するよう求めているのは、これを防ぐためです。

解決策は2つです。直接的なのは、絶対パスを調べて使う方法です。

which node
which npx

そして、JSONの "command": "npx" をその絶対パスに置き換えます。もうひとつは、設定済みのターミナルからエディタを開き、プロセスに正しいPATHを引き継がせる方法です。

要件を下回るNodeのバージョン

ShopifyのツールキットにはNode.js 18以上が必要です。nvmを使っている場合、ターミナルで有効なバージョンが、エディタから見えるバージョンと同じとは限りません。症状は、はっきりしたメッセージなしに失敗と表示されるサーバーや、起動直後に落ちるサーバーです。node -v は、シェルのパスではなく、JSONに書いた絶対パスで実行してください。

url があって type がないエントリ

環境ではなく、ファイルのエラーです。Claude Codeは type のないエントリをstdioサーバーとして読み込みます。したがって、url があって type がないエントリは無効な設定です。サーバーはスキップされ、メッセージは MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry になります。2.1.202より前のバージョンでは、同じ設定が command: expected string, received undefined と表示され、開発者を見当違いの場所に向かわせていました。別のクライアント向けに書かれた mcpServers ブロックをコピーするときは、url のあるエントリが type を宣言しているか確認してください。

貼り付けたトークンに紛れ込んだ見えない空白

Claude Codeは、設定値の先頭や末尾に空白が含まれていると警告します。改行ごと貼り付けたトークンによくあるケースです。チェック対象は、command、url、args の各項目、そして env と headers の値とキー名です。警告はフィールド名を示しますが値は表示せず、エージェントが空白を自動で削ることもありません。ファイルで修正してください。

短すぎる起動時間

最初の npx でパッケージをダウンロードするサーバーは、通常より起動に時間がかかります。Claude Codeでは、起動時間を環境変数で設定できます。

MCP_TIMEOUT=10000 claude

値はミリ秒なので、この例ではサーバーの起動に十秒の猶予を与えています。

存在しない再接続

セッションの途中で落ちたリモートサーバーは、Claude Codeが指数バックオフで、最大五回まで再接続を試みます。stdioサーバーはそうではありません。ローカルのプロセスで、自動再接続がないのです。プロセスが落ちたら、/mcp パネルから再接続するか、セッションを再起動してください。

6. シークレット、スコープ、コミットしてはいけないもの

ルートの .mcp.json はリポジトリに入れるためのものです。そして、そこにリスクがあります。JSONに直接書いたAPIキーは、コミットと一緒に出ていきます。

どちらのエディタも、変数展開でこれを解決します。Cursorは command、args、env、url、headers の中の変数を、${env:NOME}、${userHome}、${workspaceFolder}（.cursor/mcp.json を含むフォルダ）という構文で展開します。Claude Codeは ${VAR} を展開し、${VAR:-default} の形でデフォルト値も受け付けます。

共有するブロックは変数を参照し、チームの各メンバーが自分のマシンで値を設定します。

{ "mcpServers": {
  "api-interna": {
    "type": "http", "url": "https://api.exemplo.com/mcp",
    "headers": { "Authorization": "Bearer ${env:API_TOKEN}" }
  }
} }

どんな設定のテクニックよりも価値のある3つの注意点：

1. 権限は最小限のキーにします。エージェントが注文を読むだけなら、そのキーに顧客を作成する権限は要りません。
2. サードパーティのサーバーは、あなたのマシン上で、あなたの権限で動くコードです。Claude Codeのドキュメントは、接続する前にそのサーバーを信頼できるか確認するよう、はっきり求めています。外部のコンテンツを取得するサーバーは、プロンプトインジェクションのリスクにあなたをさらすからです。Cursorは、重要な連携ではソースコードを確認するよう推奨しています。
3. 機密性の高い環境では、リモートのエンドポイントではなくローカルのstdioを使います。機密データについてのCursor自身の推奨に沿ったものです。

7. サーバーが動いてから現れる限界

サーバーが接続されたからといって、フローが完成したわけではありません。ドキュメントに記載された2つの限界が、実際に使うとすぐに現れます。

出力量。 Claude Codeは、MCPツールの出力が10,000トークンを超えると警告し、デフォルトでは出力を25,000トークンに制限します。上限は MAX_MCP_OUTPUT_TOKENS で引き上げられますが、警告のしきい値は固定です。テーブルを丸ごとダンプして返すツールはこの上限にぶつかります。たいていの解決策は、上限を上げることではなく、サーバー側で絞り込むことです。

呼び出しごとの無応答。 無応答ウィンドウの間に応答も進捗通知も送らない呼び出しは、実時間の上限を待たずにエラーで中断されます。デフォルトのウィンドウは、HTTP、SSE、WebSocket、コネクタで五分、stdioで30分です。長い処理には、進捗を送信するサーバーが必要です。

出典：Claude Codeのドキュメント、MCPのページ、2026年9月21日確認。

常に電源が入っているマシンでエージェントを動かす使い方なら、このセクションの環境とPATHの考え方はそのまま当てはまります。サーバーでClaude Codeを動かし続ける話は、Hostinger VPSでClaude Codeを24/7稼働にまとめています。

よくある質問

MCPは、連携したいシステムのAPIの代わりになりますか？

いいえ。MCPはエージェントとツールをつなぐ層であり、APIはあくまでAPIです。MCPサーバーがあなたのシステムと話し、それを tools、resources、prompts として公開します。システムにAPIもアクセス可能なデータベースもなければ、MCPが存在しないアクセスを作り出すことはありません。

CursorとClaude Codeで同じ設定を使えますか？

たいていの場合は使えます。どちらも mcpServers キーを同じ形式で読みます。Claude Codeのドキュメントは、別のクライアント向けに書かれたブロックを流用するときによくある修正を2つ挙げています。url のあるエントリに type を加えること、そして英字、数字、ハイフン、アンダースコア以外の文字を含むサーバー名を変えることです。

ターミナルでは動くのに、エディタの中では失敗するのはなぜですか？

サーバーのプロセスが、あなたのターミナルではなくエディタの環境を引き継ぐからです。Nodeのバージョン管理ツールはシェルごとにPATHを変えますが、アイコンから開いたエディタはそのシェルを通りません。command フィールドに絶対パスを使うか、設定済みのターミナルからエディタを開いてください。

サードパーティのMCPサーバーは安全ですか？

誰が公開したか、何にアクセスするかによります。Claude Codeのドキュメントは、接続する前にそのサーバーを信頼できるか確認するよう求めています。外部のコンテンツを持ち込むサーバーは、プロンプトインジェクションのリスクを生むからです。Cursorは、信頼できる提供元からインストールすること、サーバーがアクセスする範囲を確認すること、権限を絞ったキーを使うこと、重要な連携ではコードを読むことを推奨しています。

エージェントにShopifyのプロジェクトを理解させるのにMCPは必要ですか？

必ずしも必要ではありません。Shopifyはツールキットを、プラグイン、エージェントスキル、Dev MCPの形で提供しており、自動更新されるプラグインを推奨の方法としています。MCPが必要になるのは、ERP、社内データベース、自社の管理画面のように、あなたしか持っていないシステムとエージェントが話す必要があるときです。

まとめ

MCPが解決するのは特定の問題です。あなたがチャットにデータを貼り付ける代わりに、エージェントにツールまでの標準化された道筋を与えることです。設定は小さく、.cursor/mcp.json と .mcp.json の2つのファイルにあり、同じ mcpServers キーを使います。壊れるのはJSONそのものではほとんどありません。エディタのPATHにないコマンド、要件を下回るNodeのバージョン、url があって type がないエントリです。まずサーバーをひとつだけ設定し、エージェントに何かを頼む前にステータスを確認し、それから2つ目を追加してください。

エージェントにあなたのERP、ストア、データベースを読ませたいなら、それはオーダーメイドの連携（MCP、Webhook、キュー）です。システムの内容と自動化したいことを oailton.dev/ja/contato からお知らせください。