MCP設定ファイルの書き方｜mcp.jsonの構造とエラー修正

公開 2026年9月8日

MCPの設定例を自分用に編集したい人へ、mcp.jsonの構造と文字列・配列・オブジェクトの読み方を解説します。サーバーの追記、argsの変更、Windowsパスの書き方、カンマや引用符の修正を短い例で確認。製品ごとの設定の違いと、JSONの構文が正しくても接続できない場合の確認順も整理します。

MCP
JSON
Cursor
設定ファイル
エラー修正
他1

配布されているmcp.jsonの例をコピーして、自分のサーバー名やパスに書き換えた途端にエラーが出た経験はないでしょうか。設定例そのものは動くのに、変更した瞬間だけ壊れるので、どこを直せばよいのか分かりにくくなります。

この記事では、設定例の対象製品を確認したうえで、値の書き換えとサーバーの追加、そして追記後によく起きる構文エラーの直し方までを順に扱います。保存場所や再起動の手順は各製品の記事に譲り、ここではmcp.jsonの中身を読み、書き換え、直すことに絞ります。

今日の結論

設定例の対象製品を確認し、固定キーと自分で変える値を分けて読みます。

サーバー設定はオブジェクト、引数は配列として編集し、既存のまとまりを保ったまま追加します。

引用符・カンマ・括弧の対応と、Windowsパスのバックスラッシュを確認します。

直す順番はJSONの構文、製品側の設定条件、実接続の3段階です。

設定例の対象製品と3つの型を確認する

Cursor向けmcp.jsonで、mcpServersオブジェクトの下にサーバー名とtype・command・args・envが階層になることを示す概念図

mcp.jsonという名前自体は複数の製品で使われていますが、キーの意味や必須項目は製品ごとに異なります。本記事の主な例はCursor向けの書式です。Claude Codeとの違いが出る箇所だけ、後半で短く対比します。

JSONの型は本来もっと多いのですが、この設定例を読むうえでは次の3つを押さえれば足ります。

型	書き方	この設定例での役割
文字列（string）	`"..."`	コマンド名、識別名、パスなど
配列（array）	`[...]`	引数（`args`）の並び
オブジェクト（object）	`{...}`	サーバーごとの設定のまとまり

配列は文字列しか入らないと思われがちですが、それは今回のargsがたまたま文字列の並びだからです。JSON全体では配列に数値やオブジェクトを混ぜることもできます。この設定例の範囲では、まず上の3つの型がどこに現れるかを見分けられれば十分です。

mcpServers・command・argsの役割を読む

Cursor向けの設定は、次のキーで組み立てます。

キー	型	役割	変更してよいか
`mcpServers`	オブジェクト	サーバー設定をまとめる入れ物	キー名は固定
サーバー名（例: `local-files`）	オブジェクトのキー	サーバーの識別名	自由に変更・追加できる
`type`	文字列	接続方式を示す（ローカル実行は`"stdio"`）	固定キー。Cursor公式のSTDIO表では必須項目
`command`	文字列	起動するコマンド	キー名は固定。値は環境に合わせる
`args`	配列	`command`に渡す引数	値は環境・用途で変える
`env`	オブジェクト	環境変数名と値の対応	変数名はサーバーの要求に合わせる
`url`	文字列	リモートサーバーの接続先	ローカル用の`command`とは別枠

読み違えやすいのは、commandやargsのようなキー名と、その値の区別です。キー名は製品側が決めた固定の語であり、翻訳や改名はしません。変えてよいのはサーバーの識別名と、その中の値だけです。envの中の変数名だけは例外で、使うサーバーが要求する名前に合わせます。

urlを持つリモートサーバーは、commandを使うローカルサーバーとは別の設定形です。両者を1つのサーバー定義に混ぜると、どちらの接続方式で読むのか製品側が判断できません。

引数を書き換え、サーバーを1つ追加する

まず1サーバーの状態を見てみます。

{
  "mcpServers": {
    "local-files": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\MCP Test"]
    }
  }
}

ここにremote-exampleというリモートサーバーを追記すると、次の形になります。

{
  "mcpServers": {
    "local-files": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "C:\\MCP Test"]
    },
    "remote-example": {
      "url": "https://example.invalid/mcp"
    }
  }
}

変わったのは2点だけです。local-filesの後にカンマを1つ足したことと、新しいサーバー名のオブジェクトをその後ろに丸ごと追加したことです。mcpServersを二重に作らず、既存のメンバーをそのまま残すのがポイントです（上のurlは説明用のダミーで、実際には接続できません）

argsの要素は、コマンドに渡す順番のまま1つずつ書きます。空白を含むパスも分割せず、1つの要素として扱います。同じサーバー名を重複させると、後から書いた側で上書きされるなどの扱いになりやすく、構文チェックだけで必ず検出できるとは限りません。

envを使う場合、変数の参照方法は製品によって書き方が変わります。

製品	変数参照の書き方	例
Cursor	`${env:NAME}`	`"API_KEY": "${env:API_KEY}"`
Claude Code	`${NAME}` または `${NAME:-既定値}`	`"API_KEY": "${API_KEY}"`

筆者が確認した範囲では、各製品の公式ドキュメントもこの書式を製品固有のものとして説明しています。envに値を書くこと自体は暗号化ではないため、秘密の値は環境変数側に置き、設定ファイルには参照だけを残します。

カンマ・引用符・Windowsパスの誤りを直す

追記した直後に出るエラーの多くは、次のような断片で再現できます。いずれも記事用に切り出した断片であり、これだけで完全な設定ファイルにはなりません。

修正対象	誤りの断片	修正後の断片
区切り不足	`{"command":"npx" "args":[]}`	`{"command":"npx","args":[]}`
末尾カンマ	`{"args":["-y",]}`	`{"args":["-y"]}`
引用符	`{'command':'npx'}`	`{"command":"npx"}`
閉じ括弧	`{"args":["-y"}`	`{"args":["-y"]}`
Windowsパス	`{"args":["C:\MCP Test"]}`	`{"args":["C:\\MCP Test"]}`

メンバーとメンバーの間にはカンマを置き、最後のメンバーの後には置きません。キーの引用符も半角の二重引用符に揃えます。シングルクォートはJSONの文字列として認識されません。

Windowsパスで特に見落としやすいのがバックスラッシュです。JSONの文字列中で\\と書くと、読み込んだ後は1つのバックスラッシュとして扱われます。1本だけ書くと次の文字と組み合わさって別の意味に解釈されることがあり、パスが正しく渡らない原因になります。

エラーが出た行だけを見て直らないときは、直前の行の区切りや、開いた括弧に対応する閉じ括弧が足りているかも確認します。なお{"args":"-y"}のように配列を使わない書き方もJSON自体としては有効ですが、このローカル設定のargsには配列を使うのが前提です。これは構文エラーではなくキーごとの型の問題なので、上の表とは分けて考えます。

構文チェックの後に製品の設定条件を確認する

設定を直すときは、次の順で確認すると原因を切り分けやすくなります。

JSONとして構文が正しいか
キーと値の型、変数参照が製品の想定どおりか
製品への反映と実際の接続ができているか

Node.jsが入っている環境では、次のようにファイルをその場で読み込んで構文だけを確認できます。

node -e 'JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8")); console.log("JSON syntax OK")' ./mcp.json

このコマンドはファイルを読み取って構文を検査するだけで、MCPサーバーを起動したり接続したりはしません。掲載したコマンドはPowerShell 7など引数がそのまま渡る環境を想定しているため、シェルによっては引用符の扱いが変わります。

JSON syntax OKと表示されても、変数が未定義のままだったり、指定したパスが存在しなかったり、そのキーを製品が受け付けなかったりする問題はパースの段階では分かりません。ファイルの保存場所や、変更後の反映確認は、Cursorの設定手順とClaude Codeの設定手順にまとめています。初回接続からツール呼び出しまでの一連の手順は、MCPの導入手順を参照してください。

MCPの設定を一通り確認したい場合は、MCP関連記事の一覧から探せます。

本記事の内容は執筆時点（2026-09-08）の情報に基づきます。標準文書と各製品の公式ドキュメントを参照して構成しており、掲載した設定例の実接続は検証していません。設定キーや変数参照の対応は製品・バージョンによって異なり、変更される可能性があります。JSONとして構文が正しいことは、接続が成功することを保証するものではありません。重要な判断は公式ドキュメントで確認してください。