Cursor MCP完全攻略：mcp.jsonの書き方からトラブル対策まで

mcp.jsonって何？なぜ設定が必要なのか

MCP（Model Context Protocol）の概要とCursorでの役割

室谷代表取締役

MCPってModel Context Protocolの略なんですけど、要はCursorから外部のツールやデータソースにつなぐための規格です。MYUUUの現場では、これでPostgreSQLやGitHubのIssueを直接読み書きしてます。

テキトー教師.AI認定講師

そうそう、最初に「MCPって何？」って聞かれますね。簡単に言うと、CursorのAIがファイルだけじゃなくて外部のAPIやデータベースも触れるようになる仕組みです。

室谷代表取締役

設定ファイルがmcp.jsonですね。これにサーバーの起動コマンドや環境変数を書いておくと、Cursorが起動時に自動で読み込んでくれます。

テキトー教師.AI認定講師

つまり、いちいちUIからポチポチ追加しなくても、JSON一つで外部連携の定義が完結するわけです。

mcp.jsonを使うメリット：UI操作との違い

テキトー教師.AI認定講師

実は以前のCursorではUIからMCPサーバーを追加できたんですが、最近のバージョン（0.47以降）だとmcp.jsonを直接編集する方式に変わったんですよね。最初は戸惑う方も多いみたいです。

室谷代表取締役

UIだと設定内容がどこにも保存されず、PCを変えたら再設定が必要になります。mcp.jsonならプロジェクトのリポジトリに含められるので、チーム全員で同じ構成を共有できる。

運用コストで考えると圧倒的にこっちの方が合理的です。

テキトー教師.AI認定講師

あと、間違って消しちゃうリスクも減ります。コード管理できるって安心感がありますね。

室谷代表取締役

グローバル設定とプロジェクト設定の2種類が選べるのもポイントです。詳細は後のセクションで触れますが、使い分けることで環境ごとに最適な構成が作れます。

どんなデータソースやツールと連携できるのか

テキトー教師.AI認定講師

MCPでつなげるのは、データベースやファイルストレージ、タスク管理ツール、コードホスティングサービスなど幅広いんですよ。公式のCursor Marketplaceにプラグインが並んでいて、コミュニティのものはcursor.directoryから探せます。

室谷代表取締役

具体的には、stdin/stdoutで動くローカルのCLIサーバーと、SSEやHTTPで動くリモートサーバーの両方に対応しています。リモートの場合は複数人で同じサーバーを共有できるので、チーム開発には便利ですね。

テキトー教師.AI認定講師

サーバーはPythonでもNode.jsでもGoでも書けるので、既存のスクリプトをそのままMCPサーバーにできるのも魅力です。

室谷代表取締役

認証が必要なケース（GitHubトークンとか）は、mcp.jsonのenvフィールドに書けば自動で渡せます。昔は手動で環境変数を設定するしかなかったんですが、今はファイル一つで完結します。

mcp.jsonの基本構文：具体的な設定例を解説

必須項目：command、args、envの書き方

室谷代表取締役

まず基本構造です。mcp.jsonは mcpServers オブジェクトの下にサーバー名をキーにして、command, args, env を並べます。

テキトー教師.AI認定講師

そうですね。command は実行するコマンド、args はその引数の配列、env は環境変数です。

APIキーなんかはここに書きます。

室谷代表取締役

例えばGitHubのトークンを環境変数で渡したい場合、env に { "GITHUB_TOKEN": "your_token" } と書く。これ、結構使います。

テキトー教師.AI認定講師

たしかに。トークン直書きは避けたいので、.env ファイルを読む方法もありますが、まずは基本の形を押さえましょう。

Node.jsサーバーとPythonサーバーの設定例

室谷代表取締役

実際の設定例を見てみましょう。Node.jsのMCPサーバーを npx で起動する場合、こんな感じです。

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-server"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

テキトー教師.AI認定講師

これで npx -y mcp-server が実行されて、標準出力でMCPのプロトコルをやりとりするわけですね。Python版だとこんな感じです。

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["mcp-server.py"],
      "env": {
        "API_KEY": "value"
      }
    }
  }
}

室谷代表取締役

どちらも基本的な構造は同じ。command を変えるだけで、Node.jsでもPythonでもGoでも動く。

これがMCPのいいところです。

リモートサーバー（SSE/HTTP）の設定方法

室谷代表取締役

ローカルで動かすCLIサーバーだけじゃなくて、リモートのMCPサーバーに繋ぐ場合は command の代わりに url を使います。

テキトー教師.AI認定講師

公式ドキュメントにも例がありますね。こんな感じです。

{
  "mcpServers": {
    "remote-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "API_KEY": "value"
      }
    }
  }
}

室谷代表取締役

SSEでもStreamable HTTPでもこの形式でOK。ヘッダーに認証情報を載せる感じです。

複数ユーザーで使うならリモートサーバーの方が管理しやすいですね。

テキトー教師.AI認定講師

そうですね。ローカルだと自分のPCで動かす必要がありますが、リモートならチームで共有できます。

複数のMCPサーバーを1つのファイルにまとめる

室谷代表取締役

もう一つ大事なのが、複数のMCPサーバーを1つのmcp.jsonにまとめられること。

テキトー教師.AI認定講師

例えばこんな感じで、mcpServers の配下に別々のサーバー名を並べるだけです。

{
  "mcpServers": {
    "file-system": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "xxx"
      }
    }
  }
}

室谷代表取締役

これだけで両方のツールが使えるようになる。設定ファイル1つで管理できるのは楽です。

テキトー教師.AI認定講師

それぞれのサーバーに個別の環境変数も設定できるので、複数のサービスをまとめて運用するときに便利ですね。

環境変数と相対パス：mcp.jsonを現場で使うための実践テク

envフィールドでAPIキーやトークンを安全に管理する

室谷代表取締役

mcp.jsonのenvフィールド、現場で一番使うのはやっぱり認証情報の管理ですよね。APIキーを直書きすると危ないし、チームで共有する時に困る。

テキトー教師.AI認定講師

たしかに。初めて触る人は「envって何に使うの？」ってなるんですが、GitHubのトークンとかをmcp.jsonに直接書かずに、環境変数で差し込めるのが一番の利点です。

室谷代表取締役

僕らもMYUUUのプロジェクトでは、各開発者が各自のenvにトークンを入れて、mcp.jsonのenvフィールドから参照してます。ソースコードに認証情報が混ざらないのは大きい。

テキトー教師.AI認定講師

そうそう。例えばmcp.jsonで "env": { "API_KEY": "${MY_API_KEY}" } みたいな感じで書けば、実際のキーはシェルの環境変数から取れますからね。

相対パスと絶対パスの使い分け、変数補間の活用法

室谷代表取締役

プロジェクトごとにmcp.jsonを置く場合、相対パスが使えるかどうかって結構重要ですよね。

テキトー教師.AI認定講師

はい。公式フォーラムでも質問が多くて、結論から言うと相対パスは使えます。

実行時のカレントディレクトリがプロジェクトルートになるので、args に ["./scripts/mcp-server.js"] と書けば動きます。

室谷代表取締役

絶対パスだと他のメンバーの環境で動かない可能性があるから、プロジェクト内にサーバースクリプトを置いて相対パスで指定するのがベストプラクティスですよね。

テキトー教師.AI認定講師

あと変数補間も使えます。$pwd や $HOME のようなシェル変数をそのままargsやcommandに書けるので、動的なパスを渡したい時に便利です。

.envファイルの指定とチームでの共有方法

テキトー教師.AI認定講師

現場でよく聞かれるのが、.env ファイルってどうやって読ませるの？という質問。mcp.jsonには直接.envを読み込む仕組みはないんですが、シェル側で読み込ませるテクニックがあります。

室谷代表取締役

具体的には、commandを "bash -c 'source .env && npx mcp-server'" みたいにすれば、 .env の内容を環境変数に展開してから起動できます。

テキトー教師.AI認定講師

とはいえ、チームで共有する場合は .env をgit管理から外して、それぞれの開発者が自分の環境変数を設定する方が安全です。mcp.json自体はGitに入れて、認証情報だけは各々で管理する。

室谷代表取締役

その辺りの設計を最初に決めておかないと、後で「動かない」って話になりますからね。ROIで言うと、最初の30分で整備しておけば、チーム全体の手戻りが減ります。

グローバル設定とプロジェクト設定：mcp.jsonの置き場所を理解する

グローバル設定（~/.cursor/mcp.json）とプロジェクト設定（.cursor/mcp.json）の違い

室谷代表取締役

まず配置場所の話ですね。グローバルは ~/.cursor/mcp.json、プロジェクトはルート直下の .cursor/mcp.json。

適用範囲が根本的に違う。

テキトー教師.AI認定講師

たしかに。グローバルは全プロジェクトで使う共通ツール向け。

プロジェクトはそのリポジトリ専用。現場でよく聞くのが「どっちに書けばいいかわからない」という声。

室谷代表取締役

MYUUUでもプロジェクトごとに必要なMCPが違うから、基本はプロジェクト設定に書いてる。APIキーみたいな秘密情報はグローバル側でenv指定する方が安全。

テキトー教師.AI認定講師

そうそう。グローバルに書いてしまうと、別のプロジェクトを開いたときにも毎回読み込まれて混乱する原因になる。

設定の優先順位と上書きルール

室谷代表取締役

両方に同じサーバ名がある場合、プロジェクト設定が優先されるんですかね？

テキトー教師.AI認定講師

その認識で合ってます。プロジェクト設定が存在すると、そのプロジェクト内ではグローバル設定を上書きする。

ただしグローバルにしか書いてないサーバは継続して使える。

室谷代表取締役

つまり、プロジェクト設定は完全な差し替えではなく、追加・上書きのイメージ。チームで共通のMCPをプロジェクト側で定義し、個人のトークンはグローバルから参照する構成が綺麗。

テキトー教師.AI認定講師

ちなみにWindowsでプロジェクト設定が効かないという報告がありましたが、UI上で手動で有効化する必要があったケースもあります。

チームで共有する際のベストプラクティス

室谷代表取締役

チームとして .cursor/mcp.json をGitで管理するのはアリだと思います。ただしenvにAPIキーを書く前提で。

テキトー教師.AI認定講師

そうですね。env フィールドに環境変数名を書いておけば、各開発者は自身のシェル設定や .env で値を注入できる。

室谷代表取締役

さらに、CursorのTeam Marketplaceで配布する方法もある。管理画面から承認されたサーバだけを一括でプロジェクトに適用できる。

テキトー教師.AI認定講師

まとめると、個人の秘密情報はグローバル、チームで統一したい設定はプロジェクトの .cursor/mcp.json に。これが現場で一番トラブルの少ない運用です。

GitHub連携とトラブル対策：mcp.jsonをチームで使いこなす

GitHub向けMCPサーバーの設定と認証

室谷代表取締役

GitHub向けのMCPサーバーって、公式ドキュメントだとリモートサーバーとして認証つきで設定するパターンが載ってますね。envフィールドにトークンを入れる書き方、たしかに必要です。

テキトー教師.AI認定講師

そうなんです。GitHub API叩くときのPersonal Access Token、直書きすると漏れる危険があるので、環境変数経由が鉄板です。

室谷代表取締役

例えばnpxでCLIサーバーを動かす場合、"env": {"GITHUB_TOKEN": "${env:GITHUB_TOKEN}"}みたいに書けます。MYUUUの現場でもこのパターン使ってますね。

テキトー教師.AI認定講師

最初に戸惑うのが、そのトークンをどこに保存するか。プロジェクトの.envに書くか、OSの環境変数にするか。

プロジェクトごとに変えたいならローカルの.env、複数プロジェクト共通ならシェルの設定ファイルが良いです。

mcp.jsonをGitHubリポジトリで管理する際の注意点

室谷代表取締役

チームでmcp.jsonをリポジトリに突っ込むとき、トークンがベタ書きされないようにするのが大前提ですね。

テキトー教師.AI認定講師

たしかに。mcp.json自体はバージョン管理してもいいんですけど、envフィールドは空にして、各開発者が自分の.envを用意する運用が現実的です。

室谷代表取締役

あと、Windowsだとプロジェクトレベルのmcp.jsonが効かないってフォーラム報告ありますね。最初は手動で有効化が必要だったりする。

テキトー教師.AI認定講師

それ、ハマる人多かったみたいです。Cursorの設定UIで一旦有効にすると動くようになるケースがあるので、もし動かなければSettings > MCPから確認するのが早いです。

OAuth認証設定のベストプラクティス

室谷代表取締役

リモートサーバーでOAuthを使う場合、mcp.jsonに静的OAuthクライアント情報を書くパターンが公式でサポートされてます。

テキトー教師.AI認定講師

プロバイダーからClient IDとSecretが発行されたら、それをheadersやurlに埋め込むイメージですね。でもやっぱりトークンは環境変数経由が安全です。

室谷代表取締役

そう、headersに直接書くとGitに載るリスクがある。MYUUUではenvフィールドにトークンを入れて、headersで参照するようにしてます。

テキトー教師.AI認定講師

良い運用ですね。OAuthはサーバー側でリフレッシュもやってくれるので、一度設定すれば割と手間いらずです。

トランスポート方式の選び方：mcp.jsonで指定する接続方法

stdio：ローカルで完結するシンプルな方式

室谷代表取締役

MCPサーバーを動かす最初の選択肢、stdioはやっぱりシンプルですよね。MYUUUでも個人用のツールはこれで済ませてます。

コストもゼロだし。

テキトー教師.AI認定講師

たしかに。初めて触る人にはまずこれを勧めます。

mcp.jsonのcommandとargsに書くだけで、ターミナルで直接実行する感覚。環境変数もenvで渡せる。

室谷代表取締役

ただ、これはあくまで一台のマシンで一人が使う用。チームで共有するなら次の方式を考えることになりますね。

SSEとStreamable HTTP：リモートサーバーへの接続

室谷代表取締役

で、チーム運用ならSSEかStreamable HTTP。公式の表を見ると、どちらもリモートサーバーを立てて複数ユーザーで使えると。

テキトー教師.AI認定講師

そう。SSEは従来からのストリーミング方式で、Streamable HTTPはより柔軟なHTTPベースの新しい方式。

mcp.jsonではurlフィールドにエンドポイントを指定するだけで接続できます。

室谷代表取締役

ここで注意したいのは、リモートサーバーを自分で運用するコスト。AWS Lambdaで動かすとか、常時起動のサーバーが必要になる。

個人ならオーバースペックになりがち。

テキトー教師.AI認定講師

そこはプロジェクトの規模次第ですね。コードレビュー用のMCPをチーム全員で使いたいなら、この方式が効きます。

認証方式（手動設定、OAuth）の選び方

室谷代表取締役

認証面も押さえておきたい。stdioは手動でAPIキーをenvに書くだけ。

シンプルだけどセキュリティは自己責任。

テキトー教師.AI認定講師

で、リモート方式だとOAuthが使える。公式ドキュメントには「Static OAuth」の話も出てきます。

クライアントIDを固定で設定できるので、毎回認証画面が出るのを避けたいときに便利です。

室谷代表取締役

とはいえOAuthの設定はちょっと手間。初期導入は手動認証で済ませて、チーム拡大時にOAuthに切り替えるのが現実的かな、とROIで考えると。

テキトー教師.AI認定講師

最初に戸惑うのは「どの方式を選べばいいか」という点ですが、要はローカル完結ならstdio、リモートかつ複数ユーザーならSSE/Streamable HTTPと覚えておけば大丈夫です。

よくあるトラブルと解決策：mcp.jsonが動かないときの対処法

Windows環境でのmcp.jsonが認識されない問題

室谷代表取締役

これ、Windows でプロジェクトレベルの .cursor/mcp.json を置いても認識されないって話、フォーラムでも結構上がってるんですよね。

テキトー教師.AI認定講師

たしかに。あれ、原因が意外と単純で、設定した後に UI で手動で有効化しないと動かないんですよ。

mcp.json は設定ファイルを置くだけで自動ロードされるわけじゃなくて、一旦「Enable」にしてあげる必要がある。

室谷代表取締役

最初にハマるポイントですね。MYUUU のチームでも「書いたのに使えない」って問い合わせが来て、結局それでした。

テキトー教師.AI認定講師

そうそう。mcp.json 自体は正しくても、Cursor の MCP パネルで該当サーバーが「Disabled」のままになってる。

UI から有効に切り替えるだけで動き出す、ってパターンがほとんどです。

UIでなくmcp.jsonが開かれる現象の対処

室谷代表取締役

あと、バージョン 0.47 から MCP の設定 UI を開くと mcp.json が直接開かれるようになった、って戸惑う人多いみたいですね。

テキトー教師.AI認定講師

そうです。以前は GUI で追加できたのが、今はエディタで JSON を直書きする方式に変わった。

で、「UIが表示されない！バグだ」ってなるんだけど、仕様変更なんですよね。

室谷代表取締役

プロジェクトごとの設定なら .cursor/mcp.json、グローバルなら ~/.cursor/mcp.json を直接編集する。ただそれだけの話。

慣れるとむしろ Git 管理しやすくて便利ですよ。

テキトー教師.AI認定講師

はい。最初は戸惑うけど、JSON なら差分も見やすいし、チーム共通の設定をプロジェクトに入れられる。

慣れてしまえばこっちの方が効率的だと感じます。

MCPツールが有効にならない、エラーが出る場合の確認ポイント

室谷代表取締役

ツールそのものが有効にならないケース。まずコマンドのパス指定が間違ってないか、実行権限はあるか、ですね。

テキトー教師.AI認定講師

特に Windows だと、npx や node のパスが通ってなくてエラーになるパターンが多い。コマンドラインで直接実行できるか、一度確認するといいです。

室谷代表取締役

あと環境変数。APIキーなどを env に書いてる場合、その値が正しいかどうか。

mcp.json の env フィールドに書くか、システムの環境変数を使うか。

テキトー教師.AI認定講師

そうですね。例えば GitHub のトークンが必要な MCP サーバーなら、env に GITHUB_TOKEN を設定する。

そこが抜けてると「Server started と出るけどツールが空っぽ」ってなる。あと、MCP サーバーのログを確認するには、Cursor のデベロッパーツールを開くと詳しいエラーが見られます。

よくある質問

Q1. 複数のMCPサーバーを1つのmcp.jsonに書けますか？

テキトー教師.AI認定講師

実は書けます。配列で並べればOKです。

ただ、初期設定だと1つずつ試すのが無難ですよ。

室谷代表取締役

複数動かすとどのサーバーがどのツールを提供してるか管理が煩雑になるんで、現場では用途ごとに分けることもありますね。

テキトー教師.AI認定講師

そうそう。最初は1つから始めて、慣れたら増やすのがおすすめです。

Q2. MCPサーバーが認識されないとき、Cursorの何を確認すればいいですか？

室谷代表取締役

まずはCursorの再起動。それでもダメならDeveloper Console（Ctrl+Shift+I）のConsoleタブでエラーを見てみてください。

テキトー教師.AI認定講師

よくあるのはパスの指定ミスや.envの読み込み漏れですね。特に相対パスを使うときはカレントディレクトリがどこになってるか意識しないとハマります。

室谷代表取締役

それと、mcp.jsonのJSONが壊れてないか。末尾のカンマとか許容されないので、バリデーションツールでチェックしたほうが早いです。

Q3. mcp.jsonをGitで管理するときの注意点はありますか？

室谷代表取締役

環境変数にAPIキーを直接書かないことですね。.envを使うか、別途シークレット管理するのが基本です。

テキトー教師.AI認定講師

公開リポジトリにキーをコミットすると漏洩リスクがあるので、mcp.jsonにはキーを書かずに $MY_API_KEY みたいなプレースホルダーにして、実際の値は環境変数に持たせるのが鉄板です。

室谷代表取締役

チームで共有するなら、mcp.example.jsonみたいなテンプレートを一緒に置いておくと親切ですね。

Q4. MCPサーバーをDockerで動かす場合、mcp.jsonの書き方は変わりますか？

テキトー教師.AI認定講師

変わりますね。Dockerの場合はcommandに docker run ... を指定するか、Docker Composeと連携する形になります。

室谷代表取締役

ただ、コンテナのネットワーク設定やボリュームマウントが絡むので、ホストで動かすより少し複雑です。個人的には開発中はホストで動かして、本番想定のときだけDockerにするのがいいんじゃないですかね。

テキトー教師.AI認定講師

そうですね。トラブルシュートもホストのほうが楽です。

Q5. MCPの通信方式はstdioとSSE以外にありますか？

室谷代表取締役

現状は主にその2つですね。stdioがローカル、SSEがリモート向き。

ただ、コミュニティではWebSocketやgRPCを試してる人もいるみたいですが、公式サポートはまだです。

テキトー教師.AI認定講師

基本的にはstdioで十分です。SSEはサーバーを別ホストで動かしたいときくらい。

余計なレイヤーを増やすとトラブルの元になることもあるので、必要になるまではstdioでいいと思います。

室谷代表取締役

その通り。特に最初はシンプルに。

まとめ

室谷代表取締役

mcp.json、最初はとっつきにくいけど、慣れるとすごく強力なんですよね。設定一つでCursorに自由にツールを追加できる。

テキトー教師.AI認定講師

そうなんですよ。設定ファイルの書き方さえ覚えれば、自分に合った開発環境が簡単に作れるようになります。

室谷代表取締役

現場でも、まずは小さなツールから始めて、徐々に拡張していくのがおすすめです。全部完璧にしようとすると挫折しやすい。

テキトー教師.AI認定講師

まずはmcp.jsonを書いて動かす。それが第一歩です。

どんなツールを連携させたいか、少し考えてみてください。

室谷代表取締役

じゃあ、皆さんの開発が少しでも快適になれば。Happy Hacking!（笑）

テキトー教師.AI認定講師

はい、お疲れさまでした。