Cursor 用 MCP 設定のテンプレート集｜.cursor／mcp.json のチーム配布とシークレット分離（要公式確認）

AI コードエディタとしてデファクトスタンダードの地位を確立しつつある Cursor ですが、その真価を引き出す鍵は MCP（Model Context Protocol） の活用にあります。しかし、多くの開発現場において、MCP サーバーの設定は「個人のローカル環境」に閉じがちです。チーム全員が同じコンテキスト（DB スキーマ、API 定義、ドキュメント）を AI に参照させるためには、プロジェクト単位での設定管理が不可欠です。

本記事では、Cursor の公式仕様に基づき、.cursor/mcp.json を利用したプロジェクト別設定の共有方法と、セキュリティ上不可欠な「シークレット分離」の具体的な実装パターンを解説します。これにより、チームメンバー全員が git clone した直後から、最適な AI 補完環境を手に入れることが可能になります。

1. Cursor における MCP 活用の現状と重要性

Model Context Protocol (MCP) は、Anthropic が公開した、AI アプリケーションと外部データソースを接続するためのオープン規格です。Cursor はこの MCP をいち早く取り入れ、エディタ内から直接外部ツール（Google Search、GitHub、PostgreSQL など）を操作できる仕組みを提供しています。

Cursor がサポートする接続方式

2024年以降のアップデートにより、Cursor の MCP 設定画面からは以下の 2 種類の接続方式が利用可能です（公式ドキュメント参照）。

• stdio: 標準入出力を通じた通信。ローカルで動作する Node.js や Python のスクリプトと連携する際の標準的な方式です。
• SSE (Server-Sent Events): HTTP 通信を通じて、リモートまたはローカルのサーバーと接続する方式です。

実務においては、プロジェクト固有の DB スキーマを読み取らせたり、社内 API の Swagger 情報を取得させたりするために stdio 方式で自作の MCP サーバーを組み込むケースが多増しています。これを「各自で Cursor の設定画面に入力してね」とする運用は、設定漏れや更新遅れの原因となります。

2. プロジェクト別設定 .cursor/mcp.json の仕様

Cursor には、エディタ全体のグローバル設定とは別に、プロジェクト（ワークスペース）ごとに MCP サーバーを定義できる隠れた仕様があります。プロジェクトのルートディレクトリに .cursor/mcp.json を配置することで、そのプロジェクトを開いている間だけ有効な MCP 設定を読み込ませることができます。

mcp.json の基本構造

設定ファイルは以下のような JSON 形式で記述します。このファイル自体はリポジトリにコミット可能ですが、API キーなどの秘匿情報を含めてはいけません。

{
"mcpServers": {
"my-project-db": {
"command": "node",
"args": ["./scripts/mcp-db-server.js"],
"env": {
"DB_PATH": "./data/main.db"
}
}
}
}

【比較表】グローバル設定 vs プロジェクト別設定

運用規模に応じて、どちらの方式を採用すべきか判断基準を整理しました。

企業の基幹システムや、特定のワークフローに特化した AI 活用を行う場合、プロジェクト別設定の利用が推奨されます。特に、高額MAツールに頼らず BigQuery 等で構築したデータ基盤と連携させるようなケースでは、プロジェクトごとに接続先を切り替える運用が標準となります。

3. チーム配布用テンプレートとシークレット分離の実践

mcp.json を直接 Git にコミットする場合、最も注意すべきは Security です。"env" セクションに直接 "OPENAI_API_KEY": "sk-..." などと記述してはいけません。

推奨される「ラッパースクリプト」パターン

現時点での Cursor の mcp.json は、.env ファイルを自動で読み込む機能を備えていません（※公式アップデートにより将来的に変更される可能性があります）。そのため、環境変数を注入するためのラッパースクリプトを介在させるのが現在のベストプラクティスです。

手順 1: テンプレートファイルの作成

まず、リポジトリには .cursor/mcp.json を直接含めるか、あるいは .cursor/mcp.json.example として配布します。

// .cursor/mcp.json
{
"mcpServers": {
"secure-api-server": {
"command": "sh",
"args": ["./.cursor/run-mcp.sh"]
}
}
}

手順 2: ラッパースクリプト（run-mcp.sh）の作成

このスクリプト内でローカルの .env を読み込み、本物の MCP サーバーを起動します。

#!/bin/bash

.cursor/run-mcp.sh
プロジェクトルートの .env を読み込む

if [ -f .env ]; then
export $(grep -v '^#' .env | xargs)
fi

本来の MCP サーバーを起動

node ./node_modules/@modelcontextprotocol/server-github/dist/index.js

※ Windows 環境が混在する場合は、run-mcp.ps1（PowerShell）も用意し、OS ごとに mcp.json を調整するか、cross-env 等の Node.js パッケージを利用します。

シークレット情報のライフサイクル管理

チームで開発を行う場合、これら API キーの管理漏れは、意図しない SaaS コストの増大を招きます。不要なアカウントやキーの放置は、セキュリティリスクだけでなくコスト管理の観点からも問題です。こうしたインフラ管理の課題については、SaaSコストとオンプレ負債を断つためのアカウント管理アーキテクチャを参考に、Entra ID 等での一元管理を検討してください。

4. チーム運用を円滑にする環境構築の自動化

MCP サーバーを自前で実装、あるいは OSS のものを利用する場合、実行環境（Node.js や Python 依存関係）のセットアップが必要です。

依存関係の共通化

プロジェクトの package.json に MCP 関連のパッケージを含めておけば、メンバーは npm install を実行するだけで準備が整います。

{
"devDependencies": {
"@modelcontextprotocol/sdk": "latest",
"mcp-server-postgresql": "latest"
},
"scripts": {
"mcp": "node ./scripts/my-mcp-server.js"
}
}

MCP サーバー自作時の注意点

Cursor 経由で MCP を利用する場合、AI は tools を介して対話します。独自のツールを定義する際は、AI が「いつ、どの引数でそのツールを呼ぶべきか」を理解できるよう、JSON Schema プロパティの description を極めて詳細に記述することが重要です。これは、SFAやCRMをデータ連携させる際のデータ定義設計と同様、AI とシステムの「接点」をいかに厳密に定義するかが成果を左右するためです。

5. よくあるトラブルと解決策（デバッグガイド）

Cursor で MCP サーバーが正しく認識されない場合、以下のステップで切り分けを行ってください。

① “Disconnected” 状態から復旧しない

• 原因: 起動コマンド（Node.js のパスなど）が間違っている、またはスクリプトがエラーで即終了している。
• 対処: ターミナルで mcp.json に記述した command と args を直接実行してみてください。標準出力に何かエラーが出ていないか確認します。

② パスが通らない（Relative Path Issue）

• 原因: Cursor はワークスペースのルートをカレントディレクトリとして MCP を起動しますが、環境によって挙動が異なる場合があります。
• 対処: mcp.json 内では極力プロジェクトルートからの相対パス（./scripts/...）を使用し、スクリプト内でも process.cwd() を意識した実装にします。

③ ログの確認方法

Cursor の出力パネル（Ctrl+Shift+U または Cmd+Shift+U）から “MCP” を選択すると、AI と MCP サーバー間の生のリクエスト/レスポンスを確認できます。ここで Parse Error などが出ている場合は、JSON の形式不良を疑ってください。

6. まとめ：Cursor 駆動開発をスケールさせるために

Cursor と MCP の組み合わせは、単なるコード補完を超え、「プロジェクトの文脈を完全に理解した自律型アシスタント」を実現します。個人のローカル設定に頼るのではなく、.cursor/mcp.json を用いてチーム全体で設定を共有し、ラッパースクリプトでセキュアにシークレットを管理する体制を構築しましょう。

こうした AI ツールの最適化は、エンジニアの生産性を劇的に向上させる一方で、管理すべきツールやキーの増大を招きます。業務全体の DX を推進するためには、エディタの設定だけでなく、Google Workspace や AppSheet を活用した業務フロー全体のデジタル化と並行して進めることが、真の効率化への近道となります。

最新の MCP 仕様については、常に Model Context Protocol 公式ドキュメント を参照し、Cursor のアップデートに合わせた最適な設定を維持してください。