Hermes で MCP を使う

このガイドでは、日々の作業のなかで Hermes Agent と MCP を実際にどう使うかを説明します。

機能ページが「MCP とは何か」を説明するものだとすれば、こちらは「短時間で安全に価値を引き出す方法」の話です。

MCP はどんなときに使うか

次のような場合に MCP を使います。

• 目的のツールがすでに MCP の形で存在していて、Hermes 用のネイティブなツールを作りたくない
• きれいな RPC の層を通して、ローカルやリモートのシステムを Hermes に操作させたい
• サーバーごとに、公開する範囲を細かく制御したい
• Hermes 本体に手を入れずに、社内の API・データベース・業務システムへつなぎたい

逆に、次のような場合は MCP を使わないでください。

• 組み込みの Hermes ツールで十分にうまく片付く
• サーバーが危険なツールを大量に公開していて、絞り込む準備ができていない
• ごく狭い連携が一つ必要なだけで、ネイティブなツールのほうが単純で安全に済む

考え方の基本

MCP はアダプタの層だと考えてください。

• Hermes はあくまでエージェント
• MCP サーバーがツールを提供する
• Hermes は起動時か再読み込み時にそれらのツールを見つける
• モデルは通常のツールと同じように使える
• 各サーバーをどこまで見せるかは利用者が決める

最後の点が重要です。よい MCP の使い方は「全部つなぐ」ことではなく、「必要なものを、役に立つ最小の範囲でつなぐ」ことです。

ステップ 1: MCP のサポートを入れる

標準のインストールスクリプトで Hermes を入れたなら、MCP のサポートは最初から含まれています（インストーラが uv pip install -e ".[all]" を実行します）。

追加機能なしでインストールしていて、あとから MCP だけを足したい場合は次のようにします。

cd ~/.hermes/hermes-agent
uv pip install -e ".[mcp]"

npm ベースのサーバーを使うなら、Node.js と npx が使える状態にしておいてください。

Python 製の MCP サーバーの多くでは、uvx が扱いやすい選択肢になります。

ステップ 2: まずは 1 台だけ追加する

安全なサーバーを 1 つだけ選んで始めます。

例として、プロジェクトのディレクトリ 1 つだけにアクセスできるファイルシステムのサーバーを挙げます。

mcp_servers:
  project_fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/my-project"]

そのうえで Hermes を起動します。

hermes chat

ここで、具体的な内容を尋ねてみます。

Inspect this project and summarize the repo layout.

ステップ 3: MCP が読み込まれたか確認する

確認する方法はいくつかあります。

• 設定が済んでいれば、Hermes のバナーやステータスに MCP の連携が表示されます
• どんなツールが使えるか Hermes に尋ねる
• 設定を変えたあとは /reload-mcp を使う
• サーバーへの接続に失敗した場合はログを確認する

実際に試すなら、次のようなプロンプトが役に立ちます。

Tell me which MCP-backed tools are available right now.

ステップ 4: すぐに絞り込みを始める

サーバーが多くのツールを公開している場合、絞り込みを後回しにしてはいけません。

例: 使いたいものだけを許可する

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]

機微なシステムでは、たいていこれが最良の既定になります。

WSL2: WSL の Hermes を Windows の Chrome につなぐ

次のような状況では、この構成が実用的です。

• Hermes を WSL2 の中で動かしている
• 操作したいブラウザが、Windows 側でふだんログインして使っている Chrome である
• WSL からだと /browser connect が扱いにくい、あるいは安定しない

この構成では、Hermes が Chrome に直接つなぐわけではありません。実際にはこうなります。

• Hermes は WSL で動く
• Hermes がローカルの stdio MCP サーバーを起動する
• その MCP サーバーは Windows との相互運用（cmd.exe や powershell.exe）を通じて起動される
• MCP サーバーが、実際に動いている Windows の Chrome セッションに接続する

図にすると次のとおりです。

Hermes (WSL) -> MCP stdio bridge -> Windows Chrome

この方式が役に立つ理由

• Windows の本物のブラウザプロファイル、クッキー、ログイン状態をそのまま使える
• Hermes はサポート対象の Unix 環境（WSL2）に留まれる
• ブラウザ操作が、Hermes 本体のブラウザ転送に頼らず MCP のツールとして公開される

おすすめのサーバー

chrome-devtools-mcp を使ってください。

Windows の Chrome で chrome://inspect/#remote-debugging からのリモートデバッグをすでに有効にしているなら、WSL 側から次のように追加します。

hermes mcp add chrome-devtools-win --command cmd.exe --args /c npx -y chrome-devtools-mcp@latest --autoConnect --no-usage-statistics

サーバーを保存したら、動作を確かめます。

hermes mcp test chrome-devtools-win

そのあと Hermes のセッションを新しく開始するか、次を実行します。

/reload-mcp

よくあるプロンプト

読み込みが済めば、Hermes は MCP の接頭辞が付いたブラウザ用ツールをそのまま使えます。たとえば次のように書きます。

调用 MCP 工具 mcp_chrome_devtools_win_list_pages，列出当前浏览器标签页。

/browser connect が適さない場面

Hermes が WSL で、Chrome が Windows で動いている場合、Chrome が開いていてデバッグ可能な状態でも /browser connect は失敗することがあります。

よくある原因は次のとおりです。

• Chrome が Windows 側のツールに見せているホストローカルのエンドポイントへ、WSL からは届かない
• 新しい Chrome のライブデバッグの仕組みは、従来の ws://localhost:9222 とは別物である
• chrome-devtools-mcp のような Windows 側の補助を経由したほうが、ブラウザに接続しやすい

そうした場合、/browser connect は同じ環境どうしの構成に使い、WSL から Windows のブラウザへ橋渡しするときは MCP を使ってください。

既知の落とし穴

• MCP から Windows の stdio 実行ファイルを使うときは、/mnt/c/Users/<you> や /mnt/c/workspace/... のような Windows 側をマウントしたパスから Hermes を起動してください。
• /root や /home/... から Hermes を起動すると、MCP サーバーが立ち上がる前に Windows が UNC のカレントディレクトリに関する警告を出すことがあります。
• chrome-devtools-mcp --autoConnect がページの列挙中にタイムアウトする場合は、Chrome のバックグラウンドタブや凍結されたタブを減らしてから再試行してください。

例: 危険な操作を禁止する

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer, refund_payment]

例: 補助的なラッパーも無効にする

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: false
      resources: false

絞り込みは何に効くのか

Hermes が MCP 経由で公開する機能には、2 つの種類があります。

1. サーバー本来の MCP ツール

• 次で絞り込みます。
  • tools.include
  • tools.exclude

1. Hermes が追加する補助的なラッパー

• 次で絞り込みます。
  • tools.resources
  • tools.prompts

目にする補助ラッパー

リソース関連:

• list_resources
• read_resource

プロンプト関連:

• list_prompts
• get_prompt

これらのラッパーが現れるのは、次の両方が満たされたときだけです。

• 設定でそれを許可している
• MCP サーバーのセッションが実際にその機能に対応している

つまり Hermes は、サーバーが持っていないリソースやプロンプトを、あるかのように見せることはありません。

よくある構成

構成 1: ローカルのプロジェクト補助

範囲を区切った作業場所について Hermes に考えさせたいときは、リポジトリ内のファイルシステムや git のサーバーを MCP でつなぎます。

mcp_servers:
  fs:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

  git:
    command: "uvx"
    args: ["mcp-server-git", "--repository", "/home/user/project"]

相性のよいプロンプト:

Review the project structure and identify where configuration lives.

Check the local git state and summarize what changed recently.

構成 2: Open Scaffold でリポジトリに作業の記録を残す

リポジトリに残された AI の作業記録（ミッション、計画、証跡のメモ、引き継ぎ用の情報、レビューやゲートの結果）を Hermes に読ませたいときは、Open Scaffold を使います。Hermes はエージェントのまま、Open Scaffold はリポジトリの中の記録のままです。

足場を用意したリポジトリ 1 つについて、サーバーを追加します。

hermes mcp add open_scaffold --command npx --args -y open-scaffold@latest mcp serve --repo /absolute/path/to/repo
hermes mcp test open_scaffold

そのうえで、公開する範囲は読み取り中心に保ちます。hermes mcp add の対話で select を選ぶか、あとから config.yaml を編集してください。

mcp_servers:
  open_scaffold:
    command: "npx"
    args: ["-y", "open-scaffold@latest", "mcp", "serve", "--repo", "/absolute/path/to/repo"]
    tools:
      include:
        - list_plans
        - get_plan
        - get_mission
        - list_evidence
        - get_evidence
        - get_status
        - search_plans
        - list_amendments
        - get_handoff
        - analyze_loop
        - gate_loop
      prompts: false

相性のよいプロンプト:

Use the Open Scaffold MCP tools to compile the current handoff packet and tell me the next legal action.

Inspect the active plans and evidence notes, then say whether this repo is ready for human review or needs another attempt.

境界についての注意:

• Open Scaffold の MCP は、既定ではローカル優先かつ読み取り専用です。
• 書き込み系のツールを使うには、サーバーを --allow-write 付きで起動する必要があります。Hermes に .osc のファイルを書き換えさせたいと明確に判断するまでは、有効にしないでください。
• Open Scaffold は作業を記録してゲートをかけるものであり、Hermes にマージ・公開・デプロイ・実行環境の起動を許可するものではありません。
• ツールのスキーマを再現可能にしたい場合は、@latest ではなく open-scaffold@<version> のように版を固定してください。

構成 3: GitHub の仕分け補助

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

相性のよいプロンプト:

List open issues about MCP, cluster them by theme, and draft a high-quality issue for the most common bug.

Search the repo for uses of _discover_and_register_server and explain how MCP tools are registered.

構成 4: 社内 API の補助

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      include: [list_customers, get_customer, list_invoices]
      resources: false
      prompts: false

相性のよいプロンプト:

Look up customer ACME Corp and summarize recent invoice activity.

こうした用途こそ、除外リストより厳格な許可リストのほうがはるかに向いています。

構成 4: ドキュメントや知識のサーバー

MCP サーバーのなかには、直接の操作というより共有の知識資産に近いプロンプトやリソースを公開しているものがあります。

mcp_servers:
  docs:
    url: "https://mcp.docs.example.com"
    tools:
      prompts: true
      resources: true

相性のよいプロンプト:

List available MCP resources from the docs server, then read the onboarding guide and summarize it.

List prompts exposed by the docs server and tell me which ones would help with incident response.

チュートリアル: 絞り込みまで含めた一連の設定

実際の進め方を順に見ていきます。

第 1 段階: GitHub の MCP を厳しい許可リスト付きで追加する

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, search_code]
      prompts: false
      resources: false

Hermes を起動して、こう尋ねます。

Search the codebase for references to MCP and summarize the main integration points.

第 2 段階: 必要になってから広げる

あとから issue の更新も必要になったら、次のようにします。

tools:
  include: [list_issues, create_issue, update_issue, search_code]

そして再読み込みします。

/reload-mcp

第 3 段階: 方針の違う 2 台目を追加する

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"
    tools:
      include: [list_issues, create_issue, update_issue, search_code]
      prompts: false
      resources: false

  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/project"]

これで Hermes は両方を組み合わせて動けます。

Inspect the local project files, then create a GitHub issue summarizing the bug you find.

MCP の力が出るのはここです。Hermes 本体を変えずに、複数のシステムをまたぐ作業ができます。

安全に使うための指針

危険なシステムには許可リストを使う

金銭に関わるもの、顧客に触れるもの、取り返しのつかない操作を含むものについては、次のようにします。

• tools.include を使う
• できるだけ小さな集合から始める

使わない補助機能は無効にする

サーバーが提供するリソースやプロンプトをモデルに見せたくないなら、切っておきます。

tools:
  resources: false
  prompts: false

サーバーの範囲は狭く保つ

たとえば次のようにします。

• ファイルシステムのサーバーは、ホームディレクトリ全体ではなくプロジェクトのディレクトリ 1 つを起点にする
• git のサーバーはリポジトリ 1 つだけに向ける
• 社内 API のサーバーは、既定で読み取り中心のツールだけを公開する

設定を変えたら再読み込みする

/reload-mcp

次のものを変えたあとに実行してください。

• include / exclude のリスト
• 有効・無効のフラグ
• resources / prompts の切り替え
• 認証ヘッダーや環境変数

症状別のトラブルシューティング

「サーバーにはつながるが、期待したツールが出てこない」

考えられる原因:

• tools.include で絞り込まれている
• tools.exclude で除外されている
• resources: false や prompts: false で補助ラッパーを無効にしている
• サーバーがそもそもリソースやプロンプトに対応していない

「設定はしたのに何も読み込まれない」

確認する点:

• enabled: false が設定に残っていないか
• コマンドや実行環境（npx、uvx など）が存在するか
• HTTP のエンドポイントに到達できるか
• 認証用の環境変数やヘッダーが正しいか

「MCP サーバーが公開しているはずの数よりツールが少ないのはなぜ？」

Hermes が、サーバーごとの方針と対応状況を踏まえたうえでツールを登録するようになったからです。これは想定どおりの動きで、たいていは望ましい挙動です。

「設定を消さずに MCP サーバーを外すには？」

次のように書きます。

enabled: false

設定は残したまま、接続と登録だけを止められます。

最初に試すとよい MCP の構成

多くの人にとって、最初に向いているサーバーは次のものです。

• ファイルシステム
• git
• GitHub
• fetch やドキュメント系の MCP サーバー
• 範囲を絞った社内 API を 1 つ

逆に、最初には向かないものは次のとおりです。

• 取り返しのつかない操作を多く含み、絞り込みもされていない大規模な業務システム
• 制約をかけられるほど自分が理解できていないもの

関連ドキュメント

• MCP（Model Context Protocol）
• FAQ
• スラッシュコマンド