Cursor MCP設定ガイド — mcp.jsonでサーバーに接続する手順

CursorでMCPサーバーに接続する設定は、.cursor/mcp.jsonまたは~/.cursor/mcp.jsonにJSONを書くだけで完結します。ローカルのコマンド起動型(stdio)とリモートのURL型(HTTP/SSE)で書式が変わり、OAuth認証が必要なサーバーには専用のauthフィールドを追加します。CursorをClaude Codeと併用する読者、あるいはCursorからの移行を検討している読者に向けて、設定例・環境変数の展開構文・よくあるつまずきをまとめます。同じMCPサーバーでもClaude・ChatGPT・Cursorで対応拡張機能に差がある点は別記事で扱っています。

本記事はCursorを導入済みで、これからmcp.jsonを設定する読者を想定しています。stdioの例を動かすには、Node.js(npxコマンド)またはPythonがローカルに入っている必要があります。mcp.jsonはCursorが自動生成するファイルではなく、自分でディレクトリとファイルを新規作成して書き始めます。

Cursorのmcp.jsonとは何か

mcp.jsonとは、CursorがMCPサーバーに接続するときに読み込む設定ファイルです。中身はmcpServersというキー1つの直下に、サーバー名をキーにした設定オブジェクトを並べる形を取ります。

置き場所は2種類あり、どちらに置くかで反映範囲が変わります。

チームで同じツールを使う前提なら、プロジェクト直下の.cursor/mcp.jsonに書きます。個人の作業でどのプロジェクトからでも呼びたいツールは~/.cursor/mcp.jsonです。ファイルは自分で新規作成します。MCP自体の仕組みはMCPとはで扱っているので、プロトコルの背景から知りたい場合はそちらを先に読みます。

mkdir -p .cursor
touch .cursor/mcp.json

ローカルサーバーをstdioで登録する手順

コマンドで起動するローカルサーバーは、type・command・args・envの4フィールドで設定します。Node.js製のサーバーをnpxで起動する例です。

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

Pythonスクリプトを直接起動する場合は、commandをpythonに変え、argsにスクリプトのパスを渡します。

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

stdioサーバーで使えるフィールドは次の5つです。

リモートサーバーをHTTP/SSEで接続する設定

すでにサーバーとして動いているリモートのMCPサーバーには、commandの代わりにurlとheadersを使います。

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

Cursorが対応するトランスポートは3種類あり、実行環境と想定ユーザー数、認証方式がそれぞれ違います。

自分だけが使うツールをさっと動かすならstdioで十分です。チームで共有する、複数人が同時に叩く前提ならSSEかStreamable HTTPを選びます。

MCPプロトコルの拡張機能についても対応は広く、CursorはTools・Prompts・Resources・Roots・Elicitationをサポートしています。インタラクティブなUIを返すApps拡張にも対応済みです。Apps拡張はプログレッシブエンハンスメント方式です。Cursor側がUIを描画できない状況でも、ツール自体は通常のテキスト応答としてそのまま動きます。

OAuth認証が必要なサーバーの設定方法

FigmaやLinearのように、リダイレクトURLの事前登録を求めてくるプロバイダがあります。固定のClient IDを発行している場合や、動的クライアント登録(Dynamic Client Registration)に対応していない場合も同様です。こうしたケースでは、urlを持つサーバー設定にauthオブジェクトを追加します。

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "your-oauth-client-id",
        "CLIENT_SECRET": "your-client-secret",
        "scopes": ["read", "write"]
      }
    }
  }
}

scopesを省略すると、Cursorは/.well-known/oauth-authorization-serverを参照して対応スコープを自動検出します。CLIENT_SECRETはプロバイダが確認用のシークレットを要求する場合だけ必要です。

コールバック先のリダイレクトURLはCursor側で固定されています。利用者がWebとデスクトップのどちらから認証するかに応じて、両方を登録しておきます。

サーバーの識別はOAuthのstateパラメータで行われます。そのため、この2つのURLはどのMCPサーバーに対しても共通で使い回せます。プロバイダ側のOAuthアプリには、認証する面に応じてどちらか、または両方のリダイレクトURIを許可リストへ登録します。

CLIENT_IDとCLIENT_SECRETは直書きせず、次のように変数展開で環境変数から読み込むのが安全です。

{
  "mcpServers": {
    "oauth-server": {
      "url": "https://api.example.com/mcp",
      "auth": {
        "CLIENT_ID": "${env:MCP_CLIENT_ID}",
        "CLIENT_SECRET": "${env:MCP_CLIENT_SECRET}"
      }
    }
  }
}

mcp.json内で環境変数を展開する構文

Cursorはcommand・args・env・url・headersの5フィールドで変数展開に対応しています。使える構文は5種類です。

プロジェクト内のスクリプトを絶対パスで指定する例です。

{
  "mcpServers": {
    "local-server": {
      "command": "python",
      "args": ["${workspaceFolder}/tools/mcp_server.py"],
      "env": {
        "API_KEY": "${env:API_KEY}"
      }
    }
  }
}

リモートサーバーのヘッダーにトークンを埋め込む例です。

{
  "mcpServers": {
    "remote-server": {
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MY_SERVICE_TOKEN}"
      }
    }
  }
}

.cursor/mcp.jsonはプロジェクト直下の普通のJSONファイルです。そのままGitで共有できます。ただしAPIキーをenvに直書きすると、リポジトリの履歴にそのまま残ります。${env:NAME}で環境変数名だけを書き、実際の値はシェルのプロファイルや各自の.envに置く運用にすれば、設定ファイル自体はチームで共有しつつ秘密情報だけ手元に残せます。

よくあるつまずきと対処

Cursorのマーケットプレイスに載っている公式プラグインは、サイドバーの「Customize」から「Add to Cursor」を押すだけでインストールとOAuth認証が完了します。コミュニティ製のサーバーはcursor.directoryから探します。mcp.jsonを自分で書くのは、マーケットプレイスに無い自作サーバーを動かしたいときと、起動オプションを細かく制御したいときです。

設定したサーバーが動かないときは、次の4点を順に見ます。

npm cache clean --force

1つのMCPサーバーが応答しなくても、他のサーバーの動作には影響しません。Cursorはサーバーごとに障害を分離する設計です。失敗したツール呼び出しは失敗として表示されるだけで、残りのサーバーはそのまま使えます。接続そのものが確立できないケースの切り分けは、MCPサーバーに接続できないときの切り分け手順でより詳しく扱っています。

会社支給のCursorで特定のMCPサーバーが動かせない場合は、自分の設定ミスより先にエンタープライズ側の制御を疑います。

Cursorはツール実行前に承認を求めるのが既定の挙動です。ツール名の横の矢印を押すと、渡される引数を確認できます。この承認フローはターミナルコマンドと同じRun Modeに従います。たとえば「Auto-review」モードでは、許可済みのMCPツールがそのまま実行され、それ以外だけが分類器を通ります。

MCP設定はツールによって何が違うか

CursorからClaude Codeへの移行、あるいは両方を併用する場合、同じmcpServersという見た目でも、ツールごとに設定ファイルの構造が違う点でつまずきやすいところです。

一番大きな違いはスコープの数です。Cursorはプロジェクトかグローバルかの2択ですが、Claude Codeはさらに「プロジェクト内だが自分だけ」というlocalスコープを持ちます。同じサーバーが複数の場所で定義されていても、local→project→user→プラグイン→claude.aiコネクターの優先順位で1つだけ接続します。重複の照合は、3スコープ間が名前、プラグインとコネクターが接続先です。

環境変数の展開構文にも互換性がありません。Claude Codeが展開するのは${VAR}と${VAR:-default}の2種で、Cursorの${env:NAME}はその対象に入りません。逆にCursorが解決する構文は${env:NAME}系の5種です。サーバー本体(npmパッケージやHTTPエンドポイントのURL)は共通して使い回せますが、mcp.jsonの中身は書き直しが必要です。

Cursorから移行する場合の設定の引き継ぎ方はCursorからClaude Codeへの移行ガイドにまとめています。Claude Code側のclaude mcp add構文とスコープの詳細はClaude Code MCP設定ガイドを参照してください。Claude Desktopのclaude_desktop_config.jsonはClaude Desktop MCP設定ガイドにまとめています。

Cursor用のmcp.jsonをClaude Codeへ持ち込むときの書き換え

両方のツールで同じリモートサーバーを使うなら、Cursorの1エントリーがそのままでは通らない場面があります。入口になるのはurlだけを書いたエントリーです。

Claude Codeの公式ドキュメントには、他のクライアント向けの設定をClaude Codeに載せ替える手順があります。Cursorのmcp.jsonに当てはめると、次の順になります。

claude mcp add-json example '{"type":"http","url":"https://api.example.com/mcp"}'
claude mcp get example

claude mcp getは接続状態を確認するコマンドです。.mcp.jsonに置いたプロジェクト共有のサーバーは、初回にclaudeを対話で起動して承認するまでPending approvalのままです。

環境変数まわりには、Cursorの感覚で書くと外れる点が2つあります。

1つ目は、未設定の変数の扱いです。名前が未設定で既定値もないと、Claude Codeはclaude mcp listと/mcpに警告を出します。それでもサーバーは読み込まれ、${VAR}の文字列が展開されないまま渡ります。

2つ目は、リモートサーバーのurlとheadersに置く資格情報の変数です。ANTHROPIC_API_KEYやANTHROPIC_AUTH_TOKEN、NPM_TOKENなどは、環境に設定してあっても空として読まれます。Bearer ${ANTHROPIC_AUTH_TOKEN}と書くと、サーバーにはBearer だけが届き、多くの場合401で拒否されます。サーバー用のトークンには、別の名前の変数を用意します。

まとめ

Cursorだけで使うなら、mcp.jsonの3パターンで足ります。Claude Codeと併用するなら、urlエントリーにtypeを足し、展開構文を${VAR}に直すところから始めます。

よくある質問

MCPサーバーは画像を返せますか

返せます。サーバー側がbase64エンコードした画像をツールの応答に含めると、Cursorはチャットにその画像を添付表示します。モデルが画像入力に対応していれば、そのまま内容を解析します。

機密情報を扱うMCPサーバーを追加しても安全ですか

条件付きで安全です。公式は次の5点を推奨しています。

• シークレットはenvに直書きせず、環境変数として渡す
• 機密性の高いサーバーは、複数人が同時に触れるSSE/Streamable HTTPでなくstdioでローカル実行する
• APIキーは必要最小限の権限に絞る
• 可能なら追加前にサーバーのソースコードを確認する
• 可能ならサーバーを隔離された環境で動かす