【2026年最新】Claude Code MCP実践ガイド｜設定から自作まで

「Claude Code に GitHub や Slack を直接読ませたい」「Codex と Claude を1セッションで往復させたい」——そういう用途に使うのが MCP（Model Context Protocol）です。

正直に言うと、僕もMCPを使い始めた当初は「なんとなく外部ツールを繋ぐやつ」くらいの認識でした。実際に設定して使い込んでみると、Claude Code の生産性が1段上がる感覚があって、今では複数の MCP サーバーを常駐させながら作業しています。

この記事では、MCPの仕組みから始めて、.mcp.json の実際の書き方、Codex MCPサーバーとの連携手順、よくある認証の罠、自作サーバーの入門まで、手を動かせるレベルで解説します。コードブロックはそのまま使えるものを置いていますので、読みながら試してみてください。

1. MCP（Model Context Protocol）とは何か——なぜClaude Codeに重要か

MCP は Anthropic が起点となって策定したオープンな標準プロトコルです。AIツールと外部ツール・データソースを繋ぐ「共通の道」として設計されており、異なるAIツール同士が相互運用できることが最大の特徴です。

プロトコルの詳細は modelcontextprotocol.io と code.claude.com/docs に公開されています（2026年5月時点の公式情報を参照しています）。

MCP以前の「外部ツール連携」との違い

MCPが登場する前、AIツールが外部データを扱う方法は各ベンダー独自の実装でした。ツールAが使えても、ツールBに乗り換えたら再実装が必要——という断絶がありました。MCP は「AIクライアント側」と「ツール提供側」の間にプロトコルを挟むことで、この断絶を解消します。

Claude Code の立場で言うと、Claude Code は MCP クライアントとして動作します。MCPサーバーを登録すれば、そのサーバーが公開しているツールを会話中に呼び出せるようになります。

通信の仕組み：stdio と SSE の2種類

MCP サーバーには大きく2種類の接続方式があります。

• stdio（標準入出力）：ローカルプロセスとして起動し、改行区切りの JSON-RPC で通信する。ほとんどの MCP サーバーはこの方式。
• SSE / HTTP：リモートサーバーに URL でアクセスする方式。チーム共有や SaaS との連携に使う。

stdio サーバーの通信フローはこうです：

Claude Code → (stdin に JSON) → MCPサーバープロセス
Claude Code ← (stdout に JSON) ← MCPサーバープロセス

メッセージ例:
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05",...}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"codex","arguments":{...}}}

Claude Code はまず initialize を送ってハンドシェイクし、その後 tools/list でサーバーが公開しているツール一覧を取得します。ツール呼び出しは tools/call メソッドで行われます。

2. Claude Code への MCP サーバー登録——3つの方法

Claude Code に MCP サーバーを登録する方法は主に3つあります。プロジェクトの性質や共有範囲によって使い分けましょう。

方法1：.mcp.json ファイルで宣言する（推奨・チーム共有に最適）

プロジェクトルートに .mcp.json を置く方法です。Git管理できるため、チームメンバーが clone すれば同じ MCP 設定が使えます。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

ポイント：env にシークレットを直書きするのは開発環境のみにしてください。本番・チーム共有の場合は環境変数として渡す設計にすること。

方法2：claude mcp add コマンドで追加する

ターミナルから1コマンドで追加できます。ローカル開発中に素早く試したいときに便利です。

# stdio サーバーの登録
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /tmp/workspace

# 登録確認
claude mcp list

# 特定サーバーの詳細確認
claude mcp get filesystem

claude mcp list の出力例：

filesystem    stdio    npx -y @modelcontextprotocol/server-filesystem /tmp/workspace
github        stdio    npx -y @modelcontextprotocol/server-github
codex         stdio    codex mcp-server

方法3：SSE / HTTP サーバーとして接続する（リモート・チーム共有用）

チームで共有する MCP サーバーを立てる場合や、SaaS の MCP エンドポイントに接続する場合は URL 方式を使います。

{
  "mcpServers": {
    "linear": {
      "type": "sse",
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

SSE 方式は OAuth 認証と組み合わせて使うことが多く、初回起動時にブラウザでの認証フローが走ります。

3. 代表的な MCP サーバーと用途——まず試すべき5つ

「どの MCP サーバーから試せばいい？」とよく聞かれます。まず以下の5つが鉄板です。

サーバー名	パッケージ / コマンド	主な用途
filesystem	@modelcontextprotocol/server-filesystem	指定ディレクトリ内のファイル読み書き・ディレクトリ一覧
github	@modelcontextprotocol/server-github	PR・Issue・コード検索・ファイル取得
slack	@modelcontextprotocol/server-slack	チャンネル読み取り・メッセージ送信
postgres	@modelcontextprotocol/server-postgres	PostgreSQL のスキーマ確認・クエリ実行
codex	codex mcp-server（Codex CLIが必要）	Codex エンジンへのコード生成・レビュー委任

filesystem と github はほぼすべての開発プロジェクトで役に立ちます。まずこの2つを設定して、Claude Code がリポジトリのファイルを直接読み書きできる状態を作るところから始めるのがおすすめです。

Deferred tools と ToolSearch の仕組み

MCP サーバーが多くなってくると、Claude Code はすべてのツールスキーマを最初から読み込まず、必要なタイミングでオンデマンドに読み込む仕組みが働きます。これが Deferred tools の挙動です。

具体的には、会話の中で「このツールを使いたい」と判断したときに ToolSearch でスキーマを取得し、取得後に初めてそのツールを呼び出せるようになります。これはレイテンシを下げるための設計で、サーバーを10個以上登録しているヘビーユーザーには恩恵が大きい仕組みです。

4. 実例：Codex MCP サーバーを Claude Code に繋ぐ

ここからが記事の核心です。Codex は codex mcp-server コマンドで自分自身を MCP サーバーとして公開できます。これを Claude Code に登録すると、Claude と Codex の往復処理を1セッション内で完結させられます。

前提：Codex CLI のインストール

# Codex CLI のインストール
npm install -g @openai/codex

# バージョン確認
codex --version

Codex MCP サーバーの登録

.mcp.json に以下を追加します：

{
  "mcpServers": {
    "codex": {
      "command": "codex",
      "args": ["mcp-server"],
      "env": {}
    }
  }
}

または CLI で：

claude mcp add codex -- codex mcp-server

実際の呼び出しパターン

登録が完了すると、Claude Code の会話中に mcp__codex__codex というツールが使えるようになります。

呼び出し時に渡すパラメータの主なものは以下です：

{
  "prompt": "このファイルの型定義を改善してください",
  "cwd": "/path/to/your/project",
  "sandbox": "workspace-write",
  "approval-policy": "never"
}

• cwd：Codex が作業するディレクトリ
• sandbox：workspace-write を指定すると、プロジェクトディレクトリ内へのファイル書き込みが許可される
• approval-policy：never にすると自動承認モードで動く（信頼できる処理のみに使うこと）

Claude → Codex 往復の実用例

事例区分: 実装パターン解説
以下は一般化された手法の解説です。数値は参考値として示します。

典型的な使い方として、Claude Code がコードを分析して方針を決め、実際のコード生成・変更を Codex に委任するパターンがあります。

1. Claude Code がリポジトリ全体の構造を把握（filesystem MCP 経由）
2. 変更方針を策定
3. mcp__codex__codex に対して具体的な実装タスクを投げる
4. Codex が実際にファイルを変更
5. Claude Code が変更内容をレビューして差分をまとめる

単純なファイル変更なら Claude Code だけで完結しますが、「大量のファイルに同じパターンの変更を加える」「複雑なリファクタリングをバッチで処理する」といった作業では Codex に委任することでコンテキスト消費を抑えられます。

5. 認証と課金の罠——Codex MCP で必ず押さえること

これは実際に何人かのエンジニアが踏んだ罠なので、強調して書いておきます。

Codex の認証方式：OAuth（サブスク枠）vs APIキー（従量課金）

Codex は2通りの認証方式があります：

• OAuth 認証（codex login）：ブラウザでログインするサブスク枠。ChatGPT Plus/Pro のサブスクリプション内で使える
• OPENAI_API_KEY 方式：環境変数で API キーを渡す従量課金ルート

罠はここです： OPENAI_API_KEY が環境変数にセットされていると、Codex は OAuth ではなく API キー経由で動作します。Claude Code から codex mcp-server を起動するとき、シェルに OPENAI_API_KEY が残っていれば、知らない間に従量課金が走り続けます。

確認と対処

# 現在の環境変数を確認
echo $OPENAI_API_KEY

# OAuth 認証でサブスク枠を使う場合は API キーを unset
unset OPENAI_API_KEY

# Codex のログイン状態を確認
codex login status

# 再ログイン（必要な場合）
codex logout && codex login

.mcp.json で env を空にしておくと、シェルの OPENAI_API_KEY が継承されてしまいます。意図的に API キーを使いたいわけでない限り、必ず unset した状態で起動することを推奨します。

また、Claude Code の接続エラーが Your access token could not be refreshed になった場合は、複数プロセスが同時にトークンリフレッシュを試みた競合が原因であることが多いです。codex logout && codex login で再認証してください。

6. よくある失敗パターン4つ——実装時の詰まりどころ

MCP を使い始めてよく遭遇するパターンを整理しました。

失敗1：OPENAI_API_KEY をセットしたまま Codex MCP を起動する

❌ サブスク枠のつもりが API キーで動作し、気づかないまま従量課金が発生する

⭕ unset OPENAI_API_KEY を確認してから codex mcp-server を起動する

# 安全な起動手順
unset OPENAI_API_KEY
codex login status  # OAuth ログイン状態を確認
claude  # Claude Code を起動

失敗2：.mcp.json に相対パスを使う

❌ "args": ["./scripts/my-mcp.js"] → Claude Code の起動ディレクトリによってパスが変わり、サーバーが見つからないエラーが出る

⭕ 絶対パスを使うか、npm パッケージ名で指定する

{
  "mcpServers": {
    "custom": {
      "command": "node",
      "args": ["/absolute/path/to/my-mcp.js"]
    }
  }
}

失敗3：stdio サーバーが stdout に余分な出力を出す

❌ MCP サーバーのコード内で console.log() を使うと、JSON-RPC メッセージに混入してパースエラーになる

⭕ サーバー側のデバッグ出力は必ず stderr に向ける

// NG
console.log("デバッグ情報");  // stdout に出る → JSON混入

// OK
console.error("デバッグ情報");  // stderr に出る → JSON非混入
process.stderr.write("debug: " + JSON.stringify(data) + "\n");

失敗4：MCP ツールを呼んでも「ツールが見つからない」エラーになる

❌ claude mcp list に表示されているのに、会話中でツールが使えない

⭕ Deferred tools の仕組みにより、まず ToolSearch でスキーマを取得する必要がある。または Claude Code を再起動してサーバーの初期化をやり直す

# Claude Code の再起動で解消することが多い
# または設定の強制再読み込み
claude mcp list  # サーバー状態の確認

7. おすすめ MCP サーバー構成——用途別セットアップ

プロジェクトの性格によって「何を繋ぐか」は変わります。以下は実際によく使われる構成パターンです。

パターンA：フルスタック Web 開発

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DATABASE_URL}"],
      "env": {}
    }
  }
}

filesystem でコードを直接読み書き、github で PR・Issue 管理、postgres でスキーマ確認やデータ検証ができます。

パターンB：AI 駆動開発（Claude + Codex の並用）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": {}
    },
    "codex": {
      "command": "codex",
      "args": ["mcp-server"],
      "env": {}
    }
  }
}

Claude Code が方針決定・レビューを担当し、バッチ的なコード変換・生成は Codex に投げるワークフローです。

パターンC：チーム開発・Slack 連携

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}",
        "SLACK_TEAM_ID": "${SLACK_TEAM_ID}"
      }
    },
    "linear": {
      "type": "sse",
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

Slack のスレッドを読んで GitHub Issue を立てたり、Linear のタスクを確認しながらコードを書いたりする、コンテキスト統合型のワークフローを実現できます。

8. 自作 MCP サーバー入門——50行で動かす最小実装

「社内ツールを Claude Code から使いたい」「特定のAPIをラップしたい」というニーズには、自作 MCP サーバーが有効です。MCP サーバーの要件はシンプルで、stdio で JSON-RPC 2.0 メッセージを処理できるプロセスであればOKです。

TypeScript SDK を使った最小実装

公式の TypeScript SDK（@modelcontextprotocol/sdk）を使うと、プロトコル実装を自分で書かずに済みます。

# プロジェクトセットアップ
mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk

// src/index.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

// サーバーのインスタンスを作成
const server = new Server(
  { name: "my-custom-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// ツール一覧を返すハンドラ
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_current_time",
      description: "現在の日時を返す",
      inputSchema: {
        type: "object",
        properties: {
          timezone: {
            type: "string",
            description: "タイムゾーン（例: Asia/Tokyo）",
          },
        },
        required: [],
      },
    },
  ],
}));

// ツール呼び出しハンドラ
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_current_time") {
    const tz = (args?.timezone as string) || "Asia/Tokyo";
    const now = new Date().toLocaleString("ja-JP", { timeZone: tz });
    return {
      content: [{ type: "text", text: `現在時刻 (${tz}): ${now}` }],
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

// stdio トランスポートで起動
const transport = new StdioServerTransport();
server.connect(transport);
process.stderr.write("MCP server started\n");

.mcp.json への登録：

{
  "mcpServers": {
    "my-custom": {
      "command": "npx",
      "args": ["ts-node", "/absolute/path/to/my-mcp-server/src/index.ts"],
      "env": {}
    }
  }
}

これで claude mcp list に my-custom が現れ、会話中に get_current_time ツールが使えるようになります。

Python SDK の場合

Python エコシステムに慣れているなら mcp パッケージが使えます。詳細は modelcontextprotocol.io のドキュメントを参照してください。

pip install mcp

# server.py
import asyncio
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types

app = Server("my-python-mcp")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="echo",
            description="入力をそのまま返す",
            inputSchema={
                "type": "object",
                "properties": {
                    "message": {"type": "string"}
                },
                "required": ["message"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "echo":
        return [types.TextContent(type="text", text=arguments["message"])]
    raise ValueError(f"Unknown tool: {name}")

async def main():
    async with stdio_server() as (read_stream, write_stream):
        await app.run(read_stream, write_stream, app.create_initialization_options())

asyncio.run(main())

9. よくある質問（FAQ）

Q1. .mcp.json はどのディレクトリに置けばいいですか？

プロジェクトルート（.git と同じ階層）に置くのが基本です。Claude Code はプロジェクトルートを検出して .mcp.json を自動で読み込みます。グローバルに全プロジェクトで使いたい場合は、claude mcp add コマンドでユーザーレベルで登録する方法もあります。

Q2. MCP サーバーの数に上限はありますか？

公式には上限は記載されていませんが、サーバーが増えると初期化時間とメモリ使用量が増加します。Deferred tools の仕組みにより、大量のサーバーを登録してもコンテキスト使用量は最初は最小限に抑えられます。ただし実用上は5〜10個程度に絞って使うほうがレスポンスが安定します。

Q3. Codex MCP は無料ですか？

Codex の codex login（OAuth 方式）を使えば、ChatGPT Plus/Pro のサブスクリプションの範囲内で利用できます（2026年5月時点の情報。最新のプラン・料金は developers.openai.com で確認してください）。OPENAI_API_KEY 経由だと別途 API 課金が発生します。

Q4. MCP サーバーの認証情報は安全に管理できますか？

.mcp.json に直接シークレットを書くのは避けてください。${ENV_VAR} のように環境変数を参照する形式、または .env ファイルと dotenv-cli を組み合わせる方法が安全です。.mcp.json はリポジトリに commit して問題ありませんが、シークレットが含まれる場合は .gitignore に追加してください。

Q5. 自作 MCP サーバーを他のチームメンバーと共有するには？

npm パッケージとして公開するか、社内 npm レジストリに登録するのが最もスムーズです。その後 .mcp.json の command を npx にして、args にパッケージ名を指定すれば、clone するだけで使えるようになります。

Q6. MCP と Function Calling の違いは何ですか？

Function Calling（OpenAI の実装）はモデルが API レスポンス内で「関数を呼んでほしい」とシグナルを返す仕組みで、クライアントアプリが実際の処理を担います。MCP は「外部プロセス（サーバー）が独立して動作し、AIクライアントがそのツールを呼び出す」というアーキテクチャです。MCP はプロバイダーに依存しない標準であるため、Claude Code から Codex のツールを呼ぶ（異なるAI間の連携）が実現できます。

Q7. MCP サーバーがクラッシュした場合はどうなりますか？

Claude Code はサーバーの異常終了を検知し、そのサーバーのツール呼び出しをエラーとして扱います。自動再起動はされないため、長時間使う場合はサーバー側で supervisord や PM2 などのプロセス監視を組み合わせることを検討してください。

10. MCP 実装における詰まりポイント——デバッグの手順

MCP のトラブルシューティングで一番効くのは「サーバーの stderr を見る」ことです。stdio MCP サーバーの stderr は Claude Code とは切り離されているため、自由にデバッグ出力を書けます。

デバッグ用の起動方法

# サーバーを単体で起動して動作確認
codex mcp-server 2>&1 | head -20

# JSON-RPC の動作をテスト
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  | codex mcp-server 2>/dev/null

正常なサーバーであれば、initialize に対して以下のようなレスポンスが返ります：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": { "tools": {} },
    "serverInfo": { "name": "codex", "version": "..." }
  }
}

Claude Code 側のログ確認

# Claude Code のデバッグログを有効にする
CLAUDE_MCP_DEBUG=1 claude

# または verbose モードで起動
claude --verbose

これで MCP の接続・初期化・ツール呼び出しのログが出力されます。「ツールが見つからない」「レスポンスが返らない」という症状の大半はここで原因が分かります。

Claude Code でのMCP実装についての詳細な事例は、Claude Code を使った CI/CD 自動修正の実装事例も参考になります。また、複数エージェントの並列実行についてはCodex と Claude Code の使い分け完全比較で詳しく解説しています。

11. まとめ——今日からできる3つのアクション

MCP は「難しそう」という印象があるかもしれませんが、実際には .mcp.json に数行書くだけで始められます。今日から試せることをまとめます。

1. 今日やること：プロジェクトルートに .mcp.json を作り、@modelcontextprotocol/server-filesystem を登録して claude mcp list で確認する。ファイル操作が Claude から直接できるようになると、体験が大きく変わります。
2. 今週中：GitHub MCP を追加して、PR や Issue を会話から参照できるようにする。コードレビューや Issue 対応の速度が上がります。
3. 今月中：Codex MCP を繋いで、Claude → Codex の委任ワークフローを試す。まず unset OPENAI_API_KEY を忘れずに。

自作サーバーは「社内 API をラップする」「特定のコマンドをツールとして公開する」など、プロジェクト固有のニーズに合わせて拡張できます。TypeScript SDK なら50行程度で動くので、週末に試してみる価値があります。

---

次回予告：Claude Code のサブエージェント（並列エージェント）機能を使って、複数タスクを同時に処理する実装パターンを紹介します。MCP と組み合わせると、さらに複雑なワークフローが組めます。

---

参考・出典

• Claude Code 公式ドキュメント（Anthropic、2026年5月時点）
• Model Context Protocol 公式仕様（modelcontextprotocol.io、2026年5月時点）
• OpenAI Developers（Codex CLI・認証情報、2026年5月時点）
• Anthropic 公式サイト（MCP 関連発表、2026年5月時点）

---

関連記事（Claude Code 実践ガイド）

• まとめ：Claude Code 実践テクニック完全ガイド（12スキル）
• プラグイン活用ガイド｜マーケットプレイス
• Skills作成ガイド｜SKILL.md入門
• Claude Code Hooks実践ガイド｜整形・通知の自動化
• ヘッドレス自動実行ガイド｜-p・SDK・CI
• Agent Teams｜複数AIで協調開発

関連記事（自動）

• ▸ API仕様変更レビューをClaude Codeで標準化｜5手順
• ▸ Terraform変更レビューをClaude Codeで標準化｜5手順
• ▸ 【2026年最新】Claude Code法人導入セキュリティ完全チェックリスト
• ▸ 【2026年最新】Anthropic公式レポートで読むAIコーディング8トレンド
• ▸ 【2026年最新】Claude Codeサブエージェント並列開発入門