MCP連携で外部ツールと接続する

MCPとは何か

MCP（Model Context Protocol）は、Hermes Agentから外部ツール・データベース・APIを直接操作するための標準プロトコルです。 たとえば、ブラウザの自動操作、外部ドキュメントの参照、図の生成など、 Hermes Agent単体ではできない操作を「MCPサーバー」を介して実現します。

イメージとしては、Hermes Agentに「新しい道具」を追加するプラグインの仕組みです。 MCPサーバーを接続するだけで、Claudeがそのツールの機能を自然言語で呼び出せるようになります。

Anthropic社のBoris Cherny氏も「Hermes Agentは、あなたのすべてのツールを使える。 Slack、BigQuery、Sentry、ブラウザ......MCPで接続すればClaudeがそのまま操作してくれる」と述べています。 コードを書くだけでなく、開発に関わるあらゆる外部システムとの連携が可能になるのがMCPの本質です。

設定方法

MCPサーバーの設定は、用途に応じて3つの場所で管理できます。

• .mcp.json（プロジェクト単位） — リポジトリのルートに配置し、チームで共有します。プロジェクト固有のMCPサーバーをここに設定します。
• claude mcp コマンド — CLIからMCPサーバーを追加・削除・一覧確認できます。設定ファイルを直接編集する必要がありません。
• settings.jsonのmcpServers — ユーザーレベルの設定で、全プロジェクト共通で使うMCPサーバーを定義します。

// .mcp.json（プロジェクトルートに配置）
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

サーバータイプは2種類あります。stdioはローカルプロセス（npx, pythonなど）として起動するタイプ、httpはリモートURLのエンドポイントに接続するタイプです。 日常的に使うのはstdioタイプがほとんどです。

MCPサーバーのセットアップ手順

「MCPサーバーを追加したいが、何をすればいいかわからない」という声をよく聞きます。 ここでは初めてMCPサーバーを追加する場合のステップバイステップの手順を解説します。

Step 1: CLIから追加する

最も簡単な方法はclaude mcp addコマンドです。 設定ファイルを手で編集する必要がなく、コマンド1つでサーバーが登録されます。

# プロジェクトスコープでContext7を追加
claude mcp add context7 -s project -- npx -y @upstash/context7-mcp

# ユーザースコープ（全プロジェクト共通）でPlaywrightを追加
claude mcp add playwright -- npx -y @playwright/mcp

-s projectを付けるとプロジェクト単位（.mcp.json）に追加されます。 省略するとユーザーレベル（~/.claude.json）に追加され、すべてのプロジェクトで使えるようになります。

Step 2: 接続を確認する

サーバーを追加したら、Hermes Agentを起動して接続状況を確認します。

# 現在登録されているMCPサーバーの一覧と状態を確認
claude mcp list

正常に接続されていれば、サーバー名とそのステータスが表示されます。 Hermes Agentのセッション内で/mcpと入力しても、接続中のMCPサーバーを確認できます。

Step 3: 動作テストする

接続が確認できたら、実際にそのMCPサーバーの機能を呼び出してみます。 たとえばContext7なら「Next.jsの最新APIを調べて」、Playwrightなら「localhost:3000を開いてスクリーンショットを撮って」と指示すれば、 MCPサーバーが呼び出されたことがターミナル上に表示されます。

Step 4: .mcp.jsonでチームと共有する

プロジェクトで使うMCPサーバーが決まったら、.mcp.jsonをリポジトリルートに作成してコミットします。 チームメンバーがリポジトリをcloneするだけで同じMCP構成が使えるようになります。

// .mcp.json — チームで共有するMCP設定
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

// 環境変数を使ったAPIキーの安全な管理
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

実用的なMCPサーバー

私が実際に使って効果を感じているMCPサーバーをカテゴリ別に紹介します。 さらに、チーム開発やサービス連携で活躍するサーバーも追加で取り上げます。

Research系

• Context7 — 最新のライブラリドキュメントをリアルタイムで参照します。 Hermes Agentの知識カットオフより新しいAPIの使い方を正確に取得できるため、 ハルシネーション（もっともらしいが間違った情報の生成）を防止できます。 私がMCPで最も重宝しているサーバーです。
• DeepWiki — GitHubリポジトリの構造化ドキュメントを取得します。 他のOSSプロジェクトの設計パターンを調査する際に便利です。

Debug系

• Playwright — ブラウザの自動操作を行います。UIテストの実行やWebページの検証に使えます。 Hermes Agentからブラウザを操作して、画面の状態を確認しながらデバッグを進められます。
• Chrome DevTools（Claude in Chrome） — 実際のChromeブラウザのコンソール、ネットワーク、DOM情報を取得します。 フロントエンド開発でのデバッグ効率が大幅に上がります。 Boris Cherny氏も「Webコードを書くときは毎回使う。他の類似MCPより安定して動く」と評価しています。

外部サービス連携系

• GitHub MCP — Issue・Pull Request・レビューコメントの操作をHermes Agentから直接行えます。 「このIssueの内容を読んで修正して」と一言で完結するワークフローが組めます。
• Slack MCP — Slackのチャンネル検索やメッセージ投稿をHermes Agent内から実行できます。 Boris Cherny氏のチームでは.mcp.jsonにSlack MCPを入れてチーム共有しており、 「Slackのバグ報告スレッドをClaudeに貼って"fix"と言うだけ。コンテキストスイッチがゼロになった」と述べています。
• Supabase MCP — Supabaseプロジェクトのデータベース操作・マイグレーション適用・Edge Function管理をHermes Agentから直接行えます。 SQLを書いて実行、テーブル一覧の確認、型定義の自動生成まで対話的に進められます。

// 外部サービス連携MCPの設定例
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@anthropic/slack-mcp"],
      "env": {
        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
      }
    }
  }
}

Document系

• Excalidraw — アーキテクチャ図やフローチャートを自動生成します。 ドキュメント作成時に図解を入れたい場合に便利です。

データベース系

• PostgreSQL / MySQL MCP — データベースに直接接続し、スキーマの確認やクエリの実行をHermes Agent内で完結できます。 テーブル設計の確認からデータの検証まで、ターミナルとDBクライアントを行き来する必要がなくなります。

Boris Cherny氏のチームではBigQuery CLIをHermes Agentから直接叩いてデータ分析を行っています。 「SQLを自分で書かなくなって6か月以上経つ」とのこと。 MCPやCLIを通じたデータベース連携は、開発効率を大きく変えるカテゴリです。

MCPの実践的な活用ワークフロー

MCPは単体で使うより、複数のツールを組み合わせたワークフローの中で真価を発揮します。 ここでは、私が実際に行っている3つのワークフローを具体的に紹介します。

ワークフロー1: GitHub MCP + コードレビュー

GitHub MCPを使えば、Pull Requestの内容確認から修正提案までをHermes Agent内で一気通貫で行えます。

• 「PR #42のレビューコメントを確認して」 — GitHub MCPがPRの差分とコメントを取得
• 「指摘された箇所を修正して」 — Hermes Agentがコードを修正
• 「修正内容をコミットしてプッシュして」 — そのまま反映

ブラウザでGitHubを開く→コードエディタに戻る→また確認......というコンテキストスイッチが完全になくなります。 Slack MCPと組み合わせれば、「Slackに来たバグ報告 → Issue確認 → 修正 → PR」まで一連の流れで処理できます。

ワークフロー2: Supabase MCP + データベース操作

Supabase MCPを使ったデータベース中心の開発ワークフローです。

• 「usersテーブルにrole列を追加するマイグレーションを作って」 — SQLマイグレーションを生成・適用
• 「型定義を再生成して」 — TypeScript型を自動生成
• 「Edge FunctionでWebhookハンドラを作ってデプロイして」 — 関数作成からデプロイまで

Supabase Dashboardとターミナルとエディタを3つ開いていた作業が、Hermes Agentの1つのセッションで完結します。 特にマイグレーションの生成と適用が対話的にできるのは、スキーマ設計の試行錯誤が多いフェーズで威力を発揮します。

ワークフロー3: Playwright + フロントエンドデバッグ

PlaywrightまたはChrome DevTools MCPを使ったUI修正のワークフローです。

• 「localhost:3000を開いてスクリーンショットを撮って」 — 現在の画面状態を取得
• 「ヘッダーの余白がおかしい。CSSを修正して」 — スクリーンショットを見ながら修正
• 「もう一度スクリーンショットを撮って確認して」 — 修正結果を即確認

Claudeにブラウザを渡さずにWebコードを書かせるのは、 「ブラウザを使わずにWebサイトを作れ」と言っているようなものです。 実際の画面を見ながら反復修正できるかどうかで、フロントエンドの完成度は大きく変わります。

4〜5個が適正数

MCPサーバーは便利ですが、入れすぎると逆効果になります。 これは感覚論ではなく、Hermes Agentのアーキテクチャに起因する構造的な問題です。

各MCPサーバーを接続すると、そのサーバーが提供する全ツールの定義（名前・説明・パラメータスキーマ）が システムプロンプトに注入されます。 つまり、MCPサーバーが増えるほど、Claudeが毎回読まなければならない「命令」の量が増えるのです。

Redditでも「15個のMCPサーバーを入れたが、実際に使うのは4個だけだった」という報告が 682件の賛同を得ています。私自身も同じ経験をしました。

実際に私が一時期導入していたデザイン系のMCPサーバーは、 使用頻度が低いにもかかわらずコンテキストを圧迫していたため、外す判断をしました。実務で頻繁に使うものだけを残すのが正解です。 目安として、常時接続するのは4〜5個までに抑えることをおすすめします。

もしプロジェクトごとに必要なサーバーが異なる場合は、 ユーザースコープには最小限（2〜3個）だけ置き、 プロジェクトスコープの.mcp.jsonで追加するという使い分けが有効です。 Sub-agentに専用のMCPを持たせる方法も、メインのコンテキストを節約する手段になります。

MCPのセキュリティ

MCPサーバーは外部ツールとの接続口になるため、セキュリティ設定が重要です。 settings.jsonでツールごとに細かく権限を制御できます。

// settings.json — MCP権限制御
{
  "permissions": {
    "allow": [
      "mcp__context7__*",                    // Context7の全ツールを許可
      "mcp__playwright__browser_snapshot"     // Playwrightはスナップショットのみ許可
    ],
    "deny": [
      "mcp__dangerous-server__*"             // 危険なサーバーの全ツールを拒否
    ]
  }
}

MCPツールの権限はmcp__サーバー名__ツール名の形式で指定します。 ワイルドカード（*）でサーバー内の全ツールを一括制御することも、 特定のツールだけを許可することもできます。

settings.jsonのMCP承認設定

.mcp.jsonに定義されたサーバーは、初回接続時にユーザーの承認が求められます。 settings.jsonで事前に承認・拒否を設定しておくことで、チーム運用が円滑になります。

// settings.json — MCP承認の制御
{
  "enableAllProjectMcpServers": true,        // .mcp.jsonの全サーバーを自動承認
  "enabledMcpjsonServers": ["context7"],     // 特定サーバーだけ自動承認
  "disabledMcpjsonServers": ["risky-server"] // 特定サーバーを拒否
}

enableAllProjectMcpServers: trueはチーム内で信頼済みの.mcp.jsonを使う場合に便利です。 外部のOSSリポジトリを開く際は、不明なMCPサーバーが自動承認されないよう注意してください。

Sub-agentとMCPの分離

Sub-agent（サブエージェント）を使う場合は、エージェント定義ファイルのmcpServersフィールドでエージェント固有のMCPサーバーを設定できます。 メインのHermes Agentとは異なるMCP構成を持たせることで、 権限の分離と最小権限の原則を実現できます。

MCPサーバーの管理コマンド

CLIからMCPサーバーを管理する主要コマンドを紹介します。

サーバーの追加

# プロジェクトスコープでContext7を追加
claude mcp add context7 -s project -- npx -y @upstash/context7-mcp

# プロジェクトスコープでPlaywrightを追加
claude mcp add playwright -s project -- npx -y @playwright/mcp

# 環境変数付きでGitHub MCPを追加
claude mcp add github -s project -e GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN} -- npx -y @modelcontextprotocol/server-github

-s projectでプロジェクト単位の設定に追加します。 省略するとユーザーレベル（全プロジェクト共通）に追加されます。-eで環境変数を渡すこともできます。--の後にMCPサーバーの起動コマンドを指定します。

サーバーの一覧確認

# 現在設定されているMCPサーバーを一覧表示
claude mcp list

サーバーの削除

# Context7を削除
claude mcp remove context7

MCPサーバーの追加・削除は即座に反映されます。 Hermes Agentを再起動する必要はなく、次のターンから新しいMCP構成が使われます。

MCPのトラブルシューティング

MCPサーバーは便利ですが、接続や動作で問題が起きることがあります。 よくある問題と対処法をまとめます。

サーバーが起動しない

最も多いトラブルです。以下を順番に確認してください。

• npxのパッケージ名が正しいか確認 — パッケージ名のtypoが原因であることが多い。npx -y パッケージ名をターミナルで直接実行して、エラーが出ないか確認する
• Node.jsのバージョン — 一部のMCPサーバーはNode.js 18以上を要求する。node -vで確認
• ネットワーク環境 — 社内プロキシやVPN環境ではnpmレジストリへのアクセスがブロックされることがある

# MCPサーバーの起動を手動でテスト
npx -y @upstash/context7-mcp

# エラーが出る場合はキャッシュクリアも試す
npm cache clean --force

認証エラー（Auth Failure）

GitHub MCPやSlack MCPなど、APIトークンが必要なサーバーで起きやすいエラーです。

• 環境変数が正しくセットされているか —.mcp.jsonで${GITHUB_TOKEN}と書いている場合、 そのシェルセッションにGITHUB_TOKENがexportされているか確認する
• トークンの権限スコープ — GitHub Personal Access Tokenならrepoスコープが必要。 Slackならchannels:readやchat:writeなどのBot Token Scopeが必要
• トークンの有効期限 — 期限切れのトークンは静かに失敗する。再生成して環境変数を更新する

タイムアウト

MCPサーバーの応答が遅い、またはハングする場合があります。

• 初回起動の遅さ — npxベースのサーバーは初回にパッケージをダウンロードするため、数十秒かかることがある。 2回目以降はキャッシュが効いて高速になる
• リモートサーバー（httpタイプ）の遅延 — ネットワーク経由のサーバーはレイテンシが高くなりがち。安定しない場合はstdioタイプへの切り替えを検討する

「ツールが見つからない」と言われる

MCPサーバーは接続されているのに、Claudeが「そのツールは使えない」と答える場合があります。

• permissions.denyで拒否していないか — settings.jsonの権限設定を確認。mcp__サーバー名__*がdenyに入っていると全ツールが使えない
• MCPサーバーが正常に接続されているか —claude mcp listでステータスを確認。disconnectedになっている場合はサーバーの再起動が必要
• サーバーの追加・削除後の反映 — 通常は即座に反映されるが、まれにHermes Agentのセッションを再起動しないと認識されないことがある