Claude Code MCPガイド：外部ツール・API接続の全手順と活用パターン

TL;DR

MCP（Model Context Protocol）は、Claude Code に外部ツール・データベース・API を接続するためのオープン標準プロトコルです。GitHub・Slack・Google Drive・PostgreSQL など既存のサーバーをそのまま使えるほか、自作のカスタムサーバーも作れます。

MCP でできること：

• Claude Code から GitHub の Issue・PR を直接操作
• Slack・Notion・Linear などの SaaS ツールにアクセス
• ローカル DB への直接クエリ
• プロジェクト固有の社内ツールを Claude Code に接続
• Claude Code 自身を MCP サーバーとして他ツールに公開

---

MCP の仕組み

MCP はクライアント（Claude Code）とサーバー（ツール提供側）が JSON-RPC でやり取りする標準プロトコルです。

Claude Code (MCP クライアント)
    ↓ JSON-RPC
MCP サーバー（GitHub / Slack / 自作ツールなど）
    ↓
外部 API / データベース / ローカルファイルシステム

Claude Code は MCP サーバーが提供するツールを、組み込みツール（Read・Bash・Edit など）と同じ感覚で呼び出せます。

---

MCP サーバーの追加方法

CLI で追加（推奨）

# HTTP トランスポート（クラウドサービス向け）
claude mcp add --transport http <name> <url>
claude mcp add --transport http github-api https://mcp.github.com/mcp \
  --header "Authorization: Bearer $GITHUB_TOKEN"

# Stdio トランスポート（ローカルプロセス向け）
claude mcp add --transport stdio <name> -- <command> [args...]
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

# 追加済みサーバーの一覧
claude mcp list

# サーバーの削除
claude mcp remove <name>

.mcp.json で管理（チーム共有に推奨）

プロジェクトルートに .mcp.json を置くと、リポジトリをクローンしたメンバー全員が同じ MCP 設定を使えます。

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    },
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres", "${DATABASE_URL}"]
    }
  }
}

.mcp.json はチームで共有するため、シークレットは環境変数（${ENV_VAR}）で参照します。シークレット自体は .env や ~/.claude/settings.local.json で管理してください。

settings.json で管理（個人設定・シークレットあり）

// ~/.claude/settings.local.json（git 管理しない）
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/mcp",
      "headers": {
        "Authorization": "Bearer ghp_your_actual_token_here"
      }
    }
  }
}

---

トランスポートの種類

トランスポート	特徴	向いているケース
http	クラウドサービスへの HTTPS 接続。認証ヘッダー指定可能	GitHub・Slack・Notion など SaaS API
stdio	ローカルプロセスを起動し stdin/stdout で通信	ローカル DB・ファイルシステム・自作ツール

---

Tool Search（v2.1.76 以降のデフォルト）

MCP サーバーが増えてツール数が多くなると、起動時にすべてのツールをコンテキストにロードするとトークンを大量消費します。Tool Search はこれを解決する遅延ロード機能です。

従来の動作：

セッション開始 → 全 MCP ツール定義をコンテキストにロード → Claude が使いたいツールを選択

Tool Search の動作：

セッション開始 → ツール定義はロードしない
Claude がタスクを理解 → 必要なツールを名前で検索 → 該当ツールのみコンテキストにロード

これにより、MCP サーバーが 10 個あっても「現在のタスクに必要なツール」だけがロードされ、トークン消費を最小化できます。

// .claude/settings.json でモード変更
{
  "env": {
    "ENABLE_TOOL_SEARCH": "auto"   // デフォルト: タスク数が閾値超えで自動切替
    // "ENABLE_TOOL_SEARCH": "1"  // 常に Tool Search を使う
    // "ENABLE_TOOL_SEARCH": "0"  // 無効化（従来の全ロード）
  }
}

---

claude mcp serve — Claude Code を MCP サーバーとして公開

Claude Code 自身を MCP サーバーとして起動すると、Claude Desktop・Cursor・Windsurf など MCP クライアントから Claude Code のツール（ファイル編集・コマンド実行など）を利用できます。

# Claude Code を MCP サーバーとして起動
claude mcp serve

# 特定のポートで起動
claude mcp serve --port 3000

活用例： Claude Desktop から「このリポジトリのファイルを読んで説明して」と依頼すると、Claude Desktop が claude mcp serve を通じてローカルのファイルシステムにアクセスできます。

---

主要な公式 MCP サーバー

GitHub（mcp.github.com）

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}

提供ツール：create_issue・list_pull_requests・search_code・get_file_contents など

Filesystem（ローカルファイル）

claude mcp add --transport stdio filesystem -- \
  npx @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

PostgreSQL

claude mcp add --transport stdio postgres -- \
  npx @modelcontextprotocol/server-postgres "postgresql://user:pass@localhost/mydb"

Puppeteer / Playwright（ブラウザ操作）

claude mcp add --transport stdio playwright -- npx @playwright/mcp@latest

E2E テストのシナリオを Claude Code に書かせて実行させる、スクリーンショットを撮って UI バグを報告させるなどの用途に使えます。

Context7（最新ドキュメント参照）

LLM の学習データが古いことに起因する「ハルシネーション」を補う用途の MCP です。プロンプト末尾に use context7 と書くと、対象ライブラリの最新公式ドキュメントを取得して回答に反映します。

# API キーは context7.com/dashboard で無料発行
claude mcp add context7 -- npx -y @upstash/context7-mcp --api-key "$CONTEXT7_API_KEY"

> Next.js App Router の Server Actions の最新仕様を踏まえて実装して。use context7

新しめのフレームワーク（Next.js / Astro / Remix 系など）でモデルの記憶が古いまま動くと事故るので、フレームワーク調査用 MCP として常時入れておく価値があります。

---

/mcp スラッシュコマンドと接続状態

CLI の claude mcp list 以外に、セッション内では /mcp で対話的に状態確認・サーバー詳細の閲覧ができます。

/mcp

各サーバーには connected / connecting... / disconnected のいずれかの状態が表示されます。起動直後は connecting... のまま数秒滞在することがあり、しばらく待っても変わらなければ起動コマンド側の問題です。詳細画面では提供ツールの一覧やエラーメッセージが見えます。

---

ツール承認と settings.local.json への自動反映

MCP ツールが初めて呼ばれるとき、Claude Code は確認プロンプトを出します。選択肢は3つあります。

選択肢	効果
Yes	今回だけ許可する
Yes, and don’t ask again for …	同じツールを以降は無確認で許可する
No, and tell Claude what to do differently	拒否し、代替アプローチを Claude に指示

「don’t ask again」を選ぶと .claude/settings.local.json の permissions.allow に該当ツール名が追記されます。

{
  "permissions": {
    "allow": [
      "mcp__context7__resolve-library-id",
      "mcp__github__create_issue"
    ]
  }
}

このファイルは gitignore 対象（個人設定）です。新しいプロジェクトで承認操作を省略したい場合は、この allow 配列を手動で雛形にしておくと初動が速くなります。逆に「危険なツールだけは確認を残したい」場合は deny 側に書いて固定できます。

---

自作 MCP サーバーの作成

社内 API・独自データベース・社内 Slack Bot などを Claude Code に接続したい場合は MCP サーバーを自作します。

TypeScript SDK を使った最小実装

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-internal-api", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// ツールの一覧を返す
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_deployment_status",
      description: "指定したサービスのデプロイ状況を取得する",
      inputSchema: {
        type: "object",
        properties: {
          service: { type: "string", description: "サービス名" }
        },
        required: ["service"]
      }
    }
  ]
}));

// ツールの実行ハンドラ
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "get_deployment_status") {
    const { service } = request.params.arguments as { service: string };
    // 実際の API 呼び出し
    const status = await fetchDeploymentStatus(service);
    return { content: [{ type: "text", text: JSON.stringify(status) }] };
  }
  throw new Error(`Unknown tool: ${request.params.name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

---

セキュリティの考慮事項

~/.claude/settings.local.json でシークレットを管理する .mcp.json はチームで共有するため Git にコミットします。API トークンなどのシークレットは必ず settings.local.json（gitignore 済み）か環境変数で参照してください。

MCP サーバーの権限を最小にする ローカル Filesystem サーバーを追加する場合は、アクセスを許可するディレクトリを必要最小限に絞ります。~/ 全体へのアクセスを許可するのは避けてください。

サードパーティ MCP サーバーに注意 信頼できる出所のサーバーのみを使用してください。MCP サーバーは Claude Code のコンテキストに情報を注入できるため、悪意のあるサーバーによる Prompt Injection のリスクがあります。

---

ハマりポイント・注意事項

環境変数の展開は起動時に行われる .mcp.json 内の ${ENV_VAR} は Claude Code の起動時に展開されます。起動後に環境変数を変更しても反映されません。

claude mcp list で接続状態を確認 設定したサーバーが認識されているか、エラーが出ていないかは claude mcp list で確認できます。

Stdio サーバーのログを確認する方法 Stdio 型サーバーのデバッグログは標準エラー出力に出ます。claude mcp add --transport stdio <name> -- npx ... 2>/tmp/mcp.log のようにリダイレクトすると確認しやすいです。

Tool Search が有効な場合、ツールが見当たらない場合がある Tool Search が有効な場合、Claude が「必要ない」と判断したツールは検索されません。特定のツールを必ず使わせたい場合は指示に明示的にツール名を含めてください。

disconnected 時の切り分け順序

/mcp で disconnected になった時の調査順序をテンプレ化しておくと早く解決できます。

1. 起動コマンドを単独で実行してエラー出力を確認する（例: npx -y @upstash/context7-mcp）。多くは依存パッケージのバージョン不整合か API キー欠如
2. Node.js / npx の存在確認（node --version / which npx）。stdio 系 MCP は npx に依存することが多い
3. Claude Code の再起動（exit → claude）。設定変更後に反映されないケースに有効
4. それでも直らなければ claude mcp remove <name> で一旦削除して再登録。.mcp.json 編集ミスのリセットに有効
5. stdio 型は stderr をリダイレクトしてログを取る（... 2>/tmp/mcp.log）

「いきなり削除→再追加」をやる前に、起動コマンド単独実行でエラーを見るのが最短ルートです。

---

参考リンク

• Connect Claude Code to tools via MCP — Claude Code Docs
• MCP サーバーレジストリ — api.anthropic.com/mcp-registry
• Model Context Protocol 公式サイト
• GitHub MCP サーバー
• MCP TypeScript SDK
• awesome-mcp-servers（コミュニティ）