CursorのMCP設定｜mcp.jsonの置き場所と追加後の確認

Cursorで自分のMCPサーバーをつなぎたいとき、管理画面から進むか、mcp.jsonを直接書くかで迷いやすいです。画面で追加できたあとも、ファイルをどこに置き、何をどこまで確認すれば使える状態かがはっきりしないことがあります。

本記事では、Cursorでmcp.jsonを設定するときの置き場所の優先順位、ローカルとリモートの書き分け、追加後に確認すべき段階までを整理します。

今日の結論

• Cursorでは、Customize（MCPs）という管理画面と、実体であるmcp.jsonの両方からMCPサーバーを設定できます。
• mcp.jsonにはプロジェクト用とグローバルの2種類があり、両方が読み込まれます。同名サーバーがある場合はプロジェクト側が優先されます。
• ローカルサーバーはcommandとargs、リモートサーバーはurlとheadersで書き分け、秘密値は${env:NAME}のような参照形にします。
• 追加後は「一覧に出ているか」「ツールを呼べるか」「承認の設定が広すぎないか」を分けて確認します。
• 反応がないときは保存先や再起動をまず疑い、一覧・呼び出し・承認のどこで止まっているかを切り分けます。

本記事は、筆者が公式ドキュメントを確認した範囲（2026-09-12時点）をもとに整理しています。実機での動作までは確認していないため、画面表示や挙動に差があれば末尾の免責もあわせてご覧ください。

設定の入口とmcp.jsonという実体を分ける

CursorのMCP設定には、2つの入り口があります。ひとつはサイドバーのCustomizeから開く管理画面で、そこにあるMCPsという項目でサーバーの一覧・追加・無効化を操作します。もうひとつが、実体のファイルであるmcp.jsonを直接編集する方法です。Cursor DocsのMCPは、この2つの経路をどちらも案内しています。

Marketplaceには公式・コミュニティのMCPサーバーが並び、ワンクリックで認証まで進められます。手軽な反面、カタログとして一覧化すると本題から外れるため、ここでは「そういう経路もある」ことに触れるだけにとどめます。本記事が中心に扱うのは、mcp.jsonを手で書く方法です。

画面の項目名はバージョンによって変わることがあります。CustomizeやMCPsという表記が見当たらない、あるいは以前のTools & MCPsという表示のまま残っている場合は、Cursor側の画面操作だけを最短でまとめた記事（CursorでのMCP追加、画面操作のまとめ）で現在の並びを確認してください。本記事はその先、mcp.jsonの置き場所と追加後の確認に絞って扱います。

Claude Desktop側の設定が必要な場合は、対象が異なるため別記事（ClaudeのMCP設定をまとめた記事）を参照してください。本記事ではCursor側の手順のみを扱います。

プロジェクト用とグローバルの置き場所・優先を決める

mcp.jsonには、置き場所が2つあります。

Cursorは両方のファイルを読み込み、内容をマージします。同名サーバーの優先ルールは単純で、勝つのはプロジェクト側という一点。ファイルは最初から用意されているわけではなく、必要になったタイミングで作る前提のため、空のテンプレートが最初から置いてあることは想定しないほうが安全です。

仕事のリポジトリだけで使うサーバーはプロジェクト用へ、個人的に毎回使う常用ツールはグローバル側へ、という分け方が扱いやすいところです。プロジェクト用のファイルをコミットする場合は、APIキーなどの秘密値を直接書き込まないようにします。具体的な書き分け方は次の項目で扱います。

ローカル起動とリモート接続を書き分ける

mcp.jsonの中身は、ローカルで起動するサーバーとリモートに接続するサーバーとで書き方が変わります。

• ローカル: commandとargsで起動コマンドを指定します。環境変数が必要ならenvも使います。現行の公式ドキュメントでは、STDIOサーバーのtypeフィールドも必須項目として扱われています。
• リモート: urlで接続先を指定し、認証ヘッダーが必要な場合はheadersを使います。

Cursor DocsのMCPは接続方式としてstdio・SSE・Streamable HTTPの3つを表にまとめていますが、それぞれの選び方の比較は本記事の範囲外です。運び方で止まったときは、MCPのstdioとSSE、選び方の比較を見てください。ここでは、ローカルはcommand起動、リモートはurl接続という大枠だけ押さえれば十分です。

秘密値は直接書かず、${env:NAME}のような参照形にします。${workspaceFolder}や${userHome}といった変数も、command・args・env・url・headersの各フィールドで使えます。

以下は構造を確認するための最小例で、そのまま貼って動く接続情報ではありません。

{
  "mcpServers": {
    "local-example": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    },
    "remote-example": {
      "url": "https://example.invalid/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

なおenvFileはSTDIOサーバー専用で、リモート接続には使えません。キーの型や追記の作法、構文エラーの直し方は別記事（mcp.jsonの書き方ガイド）にまとめています。

追加後に認識・呼び出し・承認を分けて確認する

サーバーを保存しただけでは、実際に使えるかどうかまでは分かりません。確認は次の4段階に分けると、原因を切り分けやすくなります。

1. 保存と再起動: mcp.jsonを保存した後、Cursor HelpのMCP integrationsが案内する手順に沿ってCursorを再起動します。
2. 認識の確認: Customize（MCPs）の一覧に対象のサーバーが表示されているか、無効化のトグルがオフになっていないかを見ます。一覧に出ていなければ、この時点で保存先か構文を疑います。
3. 呼び出しの確認: チャットでそのサーバーのツールを使う依頼をします。承認のダイアログが出たら、ツール名と引数を確認してから許可します。会話が「できました」と返ってきただけでは、実行結果までは判定できません。
4. 承認の強さの確認: Cursor Settings > Agents > Execution and Approvalsで、現在のRun Modeを確認します。Cursor 3.6以降はAuto-Review（既定）・Allowlist・Run Everythingの3モードがあり、Auto-Reviewは許可済みの呼び出しをすぐ実行し、それ以外を分類器で判定します。Cursor DocsのRun Modesは、いずれのモードも運用上の目安であり、迂回され得る前提で説明しています。常時すべて許可するRun Everythingのような設定は、広く許可しすぎていないか一度見直す余地があります。

この4段階を分けて見ることで、「サーバーが表示されているだけ」の状態と「実際にツールが動いて承認まで想定どおり」の状態を混同せずに確認できます。個別の許可を細かく調整したい場合は、permissions.json側で事前に許可リストを組む方法もありますが、その設計は本記事の範囲外です。

止まったらログと隣記事へ切り分ける

反応がないときは、症状ごとに確認先を変えると原因にたどりつきやすくなります。

原因をひとつに決めつけず、上から順に当たっていくのが近道です。ログはOutputパネル（Cmd/Ctrl+Shift+U）から「MCP Logs」を選ぶと、サーバー起動時のエラーや認証の失敗を確認できます。この操作はCursor HelpのMCP integrationsが案内する範囲に沿っています。

MCP関連の記事をまとめて探したいときは、MCP設定ガイドから辿れます。

本記事の内容は執筆時点（2026-09-12）の情報に基づきます。公式ドキュメントを参照して整理していますが、掲載した手順の実機動作は確認していません。設定画面の名称やファイルパス、承認の挙動はバージョンによって変わる可能性があります。接続の成功や安全性を保証するものではなく、重要な判断は公式ドキュメントで確認してください。