メインコンテンツまでスキップ

Cursor での MCP サーバーのトラブルシューティング

Cursor MCP settings panel showing a server that failed to connect

MCP サーバーは外部ツールで Cursor を拡張しますが、それらは独自の依存関係を持つ独立したプロセスであり、誤動作すると症状が紛らわしくなることがあります。赤く表示されるサーバー、更新されないツール一覧、何も起こらないように見える切断ボタンなどです。このガイドでは、Cursor での MCP 問題を診断する体系的な方法を提供します。迅速なトリアージチェックリストから、一般的な各障害モードに対する具体的な修正までを扱い、IDE の外で任意のサーバーを検証して、問題がサーバーにあるのか Cursor の接続にあるのかを判断する方法も示します。

クイックトリアージチェックリスト​

MCP サーバーが誤動作したら、この表を上から下へ順に確認してください。ほとんどの問題は最初の 3 行で解決します。

症状最初に確認すること典型的な修正
サーバーが赤く表示される、または起動しないターミナルでサーバーコマンドを手動で実行するコマンドパス、ランタイムの欠如、または環境変数を修正する
ツールが欠落している、または古い再起動せずに mcp.json を編集したか？Cursor を再起動するか、ウィンドウを再読み込みする
切断ボタンが何もしないプロセスは実際に死んでいるか？プロセスを手動で強制終了してから再接続する
サーバーがエラーになり再試行しないCursor は一部の障害後に自動再試行しないサーバーをオフとオンで切り替えるか、再起動する
リクエストがハングしてタイムアウトするサーバーの起動またはツールの実行が遅すぎる依存関係を事前ウォームし、タイムアウトを引き上げる
認証エラートークンの期限切れ、または環境変数の欠如トークンを更新し、環境を修正する

サーバーが起動しない​

最も一般的な MCP 障害は最も単純なものです。Cursor がサーバーを起動するために使用するコマンドが実際には機能しないのです。Cursor は mcp.json のコマンドを、指定した環境で正確に起動し、それが失敗するとサーバーは決して現れません。

コマンドパスが不正​

Cursor が実行するのとまったく同じようにコマンドを確認します。mcp.json が command": "npx" と書いていても、Cursor プロセス内の PATH に npx が含まれていない場合、起動は失敗します。Windows では GUI アプリケーションがターミナルとは異なる PATH を継承するため、これは特に一般的です。

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\Program Files\\nodejs\\npx.cmd",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\projects"]
    }
  }
}

実行可能ファイルへの絶対パスを使用することが Windows での確実な修正方法です。macOS と Linux では、素のコマンドが見つからない場合、which npx が絶対パスを教えてくれます。

npx または uvx の欠如​

多くの MCP サーバーは npm または Python パッケージとして配布され、npx または uvx を通じて起動されます。ランタイムがインストールされていない場合、サーバーは起動できません。

# Verify the runtimes exist
node --version    # Node 18+ for npx-based servers
npx --version
python --version
uvx --version     # install with: pip install uv

uvx がない場合は、インストールしてターミナルと Cursor を再起動し、更新された PATH が反映されるようにします。

環境変数が正しくない​

API キーを必要とするサーバーは、環境が正しくないと、しばしば起動してすぐに終了するか、起動してすべてのツール呼び出しでエラーを返します。正確な変数名についてはサーバーのドキュメントを読み、Cursor は env ブロックに記載したものだけを渡すことを覚えておいてください。

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PAT}"
      }
    }
  }
}

mcp.json 編集後にツールが再読み込みされない​

mcp.json を編集し、保存し、ツール一覧を開いても、新しいツールがそこにありません。MCP 構成はサーバープロセスが起動するときに読み込まれるため、編集がすべての状況でホットリロードされるわけではありません。

  1. ファイルを保存し、有効な JSON であることを確認します。末尾のカンマがあるとファイル全体が解析不能になり、すべてのサーバーが失敗する可能性があります。
  2. Cursor を完全に再起動するか、バージョンがコマンドパレットに再読み込みオプションを提供していればウィンドウを再読み込みします。
  3. MCP 設定パネルを開き、サーバーが接続済みとして表示されることを確認します。
  4. 新しいチャットを開始します。既存の会話は古いツール一覧をキャッシュしている可能性があるため、新しいツールは新しいセッションでのみ表示されます。
再読み込みより再起動

MCP パネルでサーバーをオフとオンで切り替えても変更が反映されない場合は、ウィンドウを完全に再読み込みするか Cursor を再起動してください。mcp.json は接続時に読み込まれ、古いプロセスはファイルが今何を言っていようと元のツール一覧を提供し続けます。

接続と再試行の問題​

切断ボタンが何もしない​

切断アクションは接続の Cursor のクライアント側を停止しますが、stdio サーバーでは、実際の子プロセスが正常にシャットダウンしない場合に生き残ることがあります。その結果、まだ半分生きているように見え、きれいな再接続を拒否するサーバーになります。ボタンが無視されるように見える場合：

# Find and kill a stubborn stdio MCP server process
# macOS / Linux:
ps aux | grep mcp
kill <PID>

# Windows PowerShell:
Get-Process | Where-Object { $_.ProcessName -like "*npx*" -or $_.ProcessName -like "*uvx*" }
Stop-Process -Id <PID> -Force

プロセスが消えたら、MCP パネルから再接続します。次の接続は現在の構成で新しいプロセスを開始します。

サーバーエラー後に再試行がない​

サーバーが起動時または初期化中にエラーを返した場合、Cursor は一般にバックグラウンドで再試行を続けません。サーバーは、あなたが介入するまで失敗状態のままです。手動再起動のオプションを、強制の度合いが増す順に示します。

  1. MCP 設定パネルでサーバーをオフとオンで切り替えます。
  2. Cursor ウィンドウを再読み込みし、すべての MCP サーバーを再接続します。
  3. Cursor を完全に終了して再起動します。
  4. プロセスが固まっている場合は、上記のように強制終了してから再接続します。

遅いサーバーでのタイムアウト​

初回実行時に依存関係をダウンロードするサーバーや、遅い外部 API を呼び出すツールは、デフォルトのタイムアウトを超え、壊れたサーバーのように見える障害を報告することがあります。典型的なケースは、npx ベースのサーバーの初回呼び出しで、何かが起動する前に npm がパッケージを取得する場合です。

# Pre-warm an npx-based server so the first real connection is fast
npx -y @modelcontextprotocol/server-github --help

ホストレベルのタイムアウトについては、多くの MCP ホスト（Cursor を含む）が従来のタイムアウト環境変数を尊重します。Cursor を起動する前にこれらを設定すると、遅いサーバーにより多くの余地を与えられます。

# macOS / Linux (add to your shell profile)
export MCP_TIMEOUT=30000        # server startup timeout in ms
export MCP_TOOL_TIMEOUT=120000  # individual tool call timeout in ms

サーバーがまだ遅すぎる場合は、別の方法でホストしてください。永続的なローカルプロセスとして実行し、セッションごとに起動するのではなく SSE または HTTP 経由で接続します。

トランスポートの種類：stdio 対 SSE/HTTP​

Cursor は 2 つの MCP トランスポートスタイルをサポートしており、いくつかのトラブルシューティング手順はそれらで異なります。

項目stdioSSE / HTTP
実行方法Cursor がプロセスを起動するサーバーは別途実行され、Cursor が URL に接続する
構成キーcommand、args、envurl（およびサポートされる場合はヘッダー）
よくある障害不正なコマンドパス、ランタイムの欠如誤った URL、認証ヘッダー、CORS またはネットワークの問題
再起動の挙動切り替えるとプロセスが再接続する再接続はリモートエンドポイントにアクセスする
デバッグコマンドを手動で実行するエンドポイントを curl し、サーバーログを確認する
{
  "mcpServers": {
    "local-stdio-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "remote-http-server": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

SSE および HTTP サーバーでは、Cursor に触れる前にエンドポイントが到達可能であることを確認してください。

# A plain GET should return something, even if it is an auth error
curl -i https://mcp.example.com/sse

401 または 403 はトランスポートが正常で、認証が問題であることを意味します。タイムアウトまたは接続拒否は、サーバーがダウンしているか URL が間違っていることを意味します。

環境変数とシークレット​

プロジェクト対グローバルの mcp.json​

Cursor は 2 つの場所から MCP 構成を読み込みます。

  • グローバル： ~/.cursor/mcp.json（Windows では %USERPROFILE%\.cursor\mcp.json）。すべてのプロジェクトに適用されます。個人用サーバーはここに置きます。あなたの GitHub トークン、データベースブラウザ、スクレイピングツールなどです。
  • プロジェクト： リポジトリ内の .cursor/mcp.json。そのプロジェクトにのみ適用され、コミットするとチームメイトと共有されます。プロジェクト固有のサーバーはここに置きます。このリポジトリのデータベース用のスキーマ MCP、このコードベースが使用するデザインツール連携などです。

サーバーが両方の場所で定義されている場合、そのプロジェクトではプロジェクト構成が支配すると考えてください。ツールが重複したり消えたりする場合は、両方のファイルで同じ名前のエントリを確認してください。

シークレットを安全に渡す​

Cursor は env ブロック内の ${VAR_NAME} プレースホルダーを環境から展開するため、シークレットを mcp.json の外に置くことができます。

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${MY_DATABASE_URL}"
      }
    }
  }
}
# Set the real value in your shell profile, not in the JSON file
export MY_DATABASE_URL="postgresql://user:password@localhost:5432/appdb"
シークレットをリポジトリにコミットしない

プロジェクトレベルの .cursor/mcp.json はリポジトリ内の通常のファイルです。リテラルの API キーが含まれていると、リポジトリをクローンするすべての人とエージェントがそのキーを取得します。機密性の高いものには ${VAR} 展開を使用し、ローカルの値を含める必要がある場合はプロジェクトの mcp.json を .gitignore に追加してください。

MCP ログの読み方​

症状が不明確な場合、通常はログが本当の問題を教えてくれます。Cursor は MCP のアクティビティを出力インフラストラクチャを通じて表示します。

  1. コマンドパレットを開き、出力パネルを表示するコマンドを実行するか、表示メニューを使用します。
  2. 出力パネルのチャネルドロップダウンで、MCP または Cursor MCP ログのチャネルを選択します。
  3. 失敗するアクションを発生させてから、最新のエントリを読みます。spawn エラー、ゼロ以外の終了コード、サーバーの stderr からのスタックトレースを探します。

典型的なログ行とその意味：

[MCP] spawn npx ENOENT                 -> the runtime was not found on PATH
[MCP] server exited with code 1        -> the server crashed; run it manually for the real error
[MCP] initialize timed out             -> slow startup; pre-warm or raise the timeout
[MCP] tool call rejected: invalid args -> the model sent a bad schema; check the tool input

サーバー側の stderr はこれらのログに転送されるため、Python のトレースバックやサーバー自体からの依存関係欠如の例外は、通常ここにそのまま現れます。

サーバーを単体で検証する​

問題が Cursor のものかサーバーのものかを証明する最速の方法は、Cursor なしでサーバーを実行することです。

コマンドを手動で実行する​

mcp.json から command と args をコピーし、素のターミナルで実行します。

# Whatever your mcp.json launches, launch it yourself
npx -y @modelcontextprotocol/server-filesystem /tmp

健全な stdio MCP サーバーは起動し、stdin 上の JSON-RPC 入力を静かに待ちます。代わりにコマンドが見つからないエラー、クラッシュ、またはパッケージのインストール失敗が表示される場合は、問題を見つけたのであり、Cursor は無実です。数文字入力して Enter を押してください。素のプロトコルエラー応答は実は良い兆候で、プロセスが JSON-RPC を話していることを証明します。

MCP インスペクターの使用​

公式の MCP インスペクターはサーバーに接続し、そのツールを一覧表示し、対話的に呼び出せるようにします。

npx @modelcontextprotocol/inspector npx -y @modelcontextprotocol/server-filesystem /tmp

これはローカルの Web インターフェースを開き、サーバーを初期化し、ツールを一覧表示し、手書きの引数で 1 つを呼び出せます。ツールがインスペクターでは機能するが Cursor では機能しない場合、違いは通常環境です。ターミナルには存在するが Cursor のプロセスには欠けている変数、または異なる作業ディレクトリです。ツールがインスペクターでも失敗する場合は、まずサーバーを修正してください。Cursor で変更しても何も助けになりません。

最小の動作する mcp.json​

構成が起動しなくなったものに漂流したときの参照として、これを使用してください。env 展開を伴う 1 つの stdio サーバーと 1 つのリモートサーバーを示しています。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/you/projects"
      ]
    },
    "remote-search": {
      "url": "https://mcp.example.com/sse",
      "env": {
        "API_TOKEN": "${MY_MCP_TOKEN}"
      }
    }
  }
}

自分のサーバーに適合させるためのチェックリスト：

  1. パッケージ名と引数を、サーバーのドキュメントのものに置き換えます。
  2. Windows で素のコマンドが見つからない場合は、実行可能ファイルの絶対パスを使用します。
  3. シークレットは ${VAR} プレースホルダーのままにし、実際の値をシェルプロファイルで設定します。
  4. JSON を検証してから Cursor を再起動し、チャットを開く前にサーバーが接続済みとして表示されることを確認します。
1 つの不正なエントリがファイル全体を壊す可能性がある

mcp.json は単一の JSON ドキュメントとして解析されます。末尾のカンマが 1 つあるか、クォートされていない値があるだけでファイル全体が無効になり、それに含まれるすべてのサーバーが一緒に起動に失敗する可能性があります。問題なく動いていたものも含めてです。複数のサーバーが同時に壊れた場合は、各サーバーを疑う前にファイルの構文を疑ってください。

クイックリファレンス​

目標これを行う
起動後にサーバーが赤くなるコマンドを手動で実行し、パス、ランタイム、または env を修正する
新しいツールが表示されないウィンドウを再読み込みしてから、新しいチャットを開始する
切断が応答しない子プロセスを強制終了してから再接続する
繰り返しの失敗、再試行なしサーバーをオフとオンで切り替えるか、Cursor を再起動する
初回実行のタイムアウトパッケージを事前ウォームし、タイムアウト環境変数を引き上げる
サーバーを疑い、Cursor ではない手動実行または MCP インスペクターで検証する
Cursor を疑い、サーバーではないenv をターミナルと差分し、MCP ログチャネルを読む