MCP（Model Context Protocol）

MCP を使うと、Hermes Agent は外部のツールサーバーにつながり、Hermes の外にあるツールを使えるようになります。GitHub、データベース、ファイルシステム、ブラウザの仕組み、社内の API など、いろいろなものが対象です。

すでにどこかにあるツールを Hermes に使わせたい、と思ったことがあるなら、たいていは MCP が一番きれいな方法です。

MCP で得られるもの

• Hermes 独自のツールを先に書かなくても、外部のツール群を使えます
• ローカルの stdio サーバーと、リモートの HTTP MCP サーバーを同じ設定にまとめられます
• 起動時にツールを自動で見つけて登録します
• サーバーが対応していれば、MCP のリソースとプロンプトを包む補助ツールも用意します
• サーバーごとの絞り込みができるので、本当に Hermes に見せたい MCP のツールだけを出せます

手早く始める

1. MCP の対応は標準のインストールに含まれています。追加の手順は要りません。

1. ~/.hermes/config.yaml に MCP サーバーを足します。

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

1. Hermes を起動します。

hermes chat

1. MCP に支えられた機能を Hermes に頼みます。

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

List the files in /home/user/projects and summarize the repo structure.

Hermes は MCP サーバーのツールを見つけ、他のツールと同じように使います。

カタログ: Nous が確認した MCP をワンクリックで入れる

Hermes には、Nous のスタッフが確認して取り込んだ MCP サーバーのカタログが 付いています。既定ではどれも無効なので、本当に使いたいものだけを入れてください。

hermes mcp                # interactive picker (default)
hermes mcp catalog        # plain-text list, scriptable
hermes mcp install n8n    # install a catalog entry by name

選択画面では、それぞれの項目がいまの状態とともに並びます。

n8n          available              Manage and inspect n8n workflows from Hermes
linear       enabled                Linear issue/project management (remote OAuth)
github       installed (disabled)   GitHub repo + PR tools

行の上で Enter を押すと、インストール（必要な認証情報の入力も含めて進みます）、 有効化、無効化、削除ができます。カタログの項目は hermes-agent のリポジトリの optional-mcps/ の下にあり、そのディレクトリに入っていること自体が Nous の 承認を意味します。コミュニティからの投稿枠はなく、項目は PR を取り込む形で追加されます。

カタログの項目が求めるものは、次のいずれかです。

• API キー — Hermes がインストール時に尋ね、その値を ~/.hermes/.env に

書きます。秘密でない値（ベースの URL など）も同じファイルに入ります。

• OAuth（リモートの MCP） — 設定には auth: oauth として書かれ、MCP の

クライアントが最初の接続でブラウザを開きます。

• OAuth（Google や GitHub などの第三者のサービス） — まだ認証していなければ、

Hermes が hermes auth <provider> を案内します。

インストール時のツールの選択

認証情報の設定が済むと、Hermes は MCP サーバーに問い合わせて、そこにあるツールを すべて並べたチェック欄を出します。

Select tools for 'linear' (SPACE toggle, ENTER confirm)
  [x] find_issues       Find issues matching a query
  [x] get_issue         Get a single issue
  [x] create_issue      Create a new issue
  [ ] delete_workspace  Delete a Linear workspace
  ...

あらかじめチェックが入っている行は、次の順で決まります。

1. 前回のあなたの選択。この項目を以前に入れたことがある場合です（入れ直しても

前の選択が残り、マニフェストの既定に上書きされません）

1. マニフェストの tools.default_enabled。項目がそれを宣言している場合です

（カタログの項目によっては、状態を変えるツールやめったに使わないツールを あらかじめ外してあります）

1. どちらにも当てはまらなければ すべて

自動生成でツールが非常に多い項目（たとえば cloudflare は OpenAPI の エンドポイントのツールがおよそ 3,300 個あります）は、代わりに tools.default_excluded を宣言します。名前とグロブの型を選んで並べた拒否の一覧です。こうした項目を インストールするときはチェック欄が出ず、tools.exclude が書かれます。当てはまらな かったものはすべて有効なままで、サーバーがあとから足したツールも含まれます。 まとめて有効に戻したいときは、config.yaml の mcp_servers.<name>.tools.exclude を編集してください。

チェック欄は ENTER で確定します。チェックしたツールだけが mcp_servers.<name>.tools.include に入ります。すべてを選んだ場合は絞り込みが 書かれません（設定が一番すっきりし、動きは同じです）。

問い合わせに失敗した場合（サーバーに届かない、OAuth がまだ済んでいない、 裏側のサービスが動いていない）も、インストール自体は成功します。マニフェストの tools.default_enabled がそのまま適用されるか（宣言されていれば）、絞り込みが 書かれません（宣言が無ければ）。サーバーに届くようになったら hermes mcp configure <name> をもう一度実行して調整してください。

信頼の考え方

カタログの項目を入れると、マニフェストに書かれたものがそのまま実行されます。git clone、 その項目の bootstrap のコマンド（pip install、npm install など）、そして最終的には MCP サーバー自身のコードです。マニフェストは hermes-agent リポジトリへの PR レビューを 通っているので、公開前に Nous が各項目を確認しています。とはいえ 入れる前に自分でもマニフェストを読むべきです。とくに source: の項目にあるリポジトリ、install.bootstrap: のコマンド、そして transport.command: の呼び出しです。

マニフェストは GitHub の optional-mcps/<name>/manifest.yaml にあります。選択画面もインストール時にマニフェストの source: の URL を表示するので、 上流のリポジトリをすぐ確かめられます。Web のダッシュボードの MCP のページでも、 カタログの項目ごとに同じ内容が見られます。通信の方式、認証の種類、エンドポイントの URL（HTTP の場合）またはコマンドと引数（stdio の場合）、git のインストール元と参照先、 bootstrap のコマンド、設定の注意点までが並び、source: はクリックできるリンクとして 表示されるので、Install を押す前に、その項目が何につなぎ何を実行するのかを正確に 確かめられます。

マニフェストの版の互換性

マニフェストは manifest_version を固定しています。カタログは新しい版にも耐える 作りです。あなたの入れている Hermes が理解するより新しい manifest_version の項目が PR で追加された場合、選択画面はその項目を黙って隠すのではなく、警告 （⚠ '<name>' requires a newer Hermes）を出します。これが見えたら hermes update で 最新の Hermes を入れてください。

実行時の ${ENV_VAR} の置き換え

項目の transport.command、transport.args、transport.url、headers の中では、 ${VAR} の書き方がサーバーへの接続時に環境変数から解決されます（~/.hermes/.env の 中身もすべて含みます）。これは、カタログの項目が、利用者が別のところで設定した値を 参照したいときに便利です。たとえば ${HOME}/foo や ${MY_PROVIDER_TOKEN} です。

Cursor 風の文脈の変数も置き換えられます（大文字と小文字を区別します）。 ${userHome}（ホームディレクトリ）、${workspaceFolder}（セッションの作業場所の 起点）、${workspaceFolderBasename}、そして ${pathSeparator} / ${/} （OS のパスの区切り文字）です。詳しくは MCP 設定の詳しい説明 を参照してください。

これは、カタログのマニフェストで使う ${INSTALL_DIR} とは別ものです。あちらは インストール時に、カタログがその項目のリポジトリを複製した場所に置き換えられます。

あとからツールの選択を変える

hermes mcp configure linear

いまの選択にチェックが入った状態で、同じチェック欄がもう一度開きます。もっと多くの ツールを有効にしたいときや、サーバーが新しいツールを足したので使いたいときに使います。

カタログのマニフェストを更新する

MCP が自動で更新されることはありません。Hermes を更新したあと、マニフェストの版が 変わっていたら、hermes mcp install <name> をもう一度実行して入れ直してください。

カタログに MCP を追加するには、 optional-mcps/ に PR を出してください。

提案の情報（suggest:）

マニフェストには、keywords: や hosts: の並びを持つ任意の suggest: の部分を 書けます。画面の側（いまのところデスクトップアプリの入力欄）はこれを使って、 書きかけの文にその語が単語として現れたときや、貼り付けたリンクのホスト名が挙げられた 接尾辞で終わるときに、ワンクリックの「Add <server>」のボタンを出します。 これはあくまで助言で、インストールは同じ検証済みのカタログや設定の経路を通ります。 ホスト型のリモートの項目のほとんど（Atlassian、Sentry、Notion、Stripe、Vercel、 Supabase など）がこれを宣言しています。

GitHub はあえてカタログに入れて いません。ホスト型の MCP はクライアントごとに 自前の OAuth アプリを求め（一般的な動的クライアント登録は拒否されます）、しかも Hermes に同梱されている github/* のスキルが gh CLI を動かすほうが、より多くのことを できるからです。デスクトップでは、GitHub に言及すると、まだ gh にサインインして いない場合に github-auth のスキルを勧めます。

MCP サーバーの二つの形

stdio サーバー

stdio のサーバーは、手元の子プロセスとして動き、標準入出力でやり取りします。

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "***"

stdio のサーバーが向いているのは、次のときです。

• サーバーが手元にインストールされている
• 手元の資源に待ち時間少なく触りたい
• 参照している MCP サーバーの説明が command、args、env を示している

HTTP サーバー

HTTP の MCP サーバーは、Hermes が直接つなぎに行くリモートのエンドポイントです。

mcp_servers:
  remote_api:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ***"

HTTP のサーバーが向いているのは、次のときです。

• MCP サーバーが別の場所で動いている
• 組織が社内向けの MCP のエンドポイントを出している
• その連携のために Hermes に子プロセスを起動させたくない

OAuth で認証する HTTP サーバー

ホスト型の MCP サーバーの多く（Cloudflare、Linear、Sentry、Atlassian、Asana、Figma、Stripe など）は、固定のトークンではなく OAuth 2.1 を求めます。auth: oauth を設定すれば、あとは Hermes が MCP の Python SDK を通して、情報の取得、クライアントの識別、PKCE、トークンの交換、更新、追加認証までを扱います。

Hermes は、対応しているサーバーには Client ID Metadata Document で自分を名乗り、対応していないサーバーでは動的クライアント登録に切り替えます。どちらも自動なので、設定することはありません。

mcp_servers:
  linear:
    url: "https://mcp.linear.app/mcp"
    auth: oauth

最初につなぐとき、Hermes は認可の URL を表示し、可能ならブラウザを開き、手元のループバックのポートで OAuth の戻りを待ちます。トークンは ~/.hermes/mcp-tokens/<server>.json に 0o600 の権限で保存され、次からは更新に失敗するまで黙って使い回されます。

リモートや画面の無いホストの場合。 Hermes がブラウザとは別の機械で動いていると、ループバックの戻りはあなたのノートパソコンに届きません。手順を終える方法は二つあります。

• 貼り戻し（準備不要）: 対話できる端末なら、Hermes は認可の URL と一緒に「Or paste the redirect URL here…」と表示します。その URL をブラウザで開いて承認し、たどり着いた URL をまるごとコピーして（戻り先は接続エラーになりますが、それで正常です）、プロンプトに貼り付けてください。?code=…&state=… のクエリ文字列だけでも通ります。
• SSH のポート転送: 別の端末で ssh -N -L <port>:127.0.0.1:<port> user@host を実行し、あとは戻りをそのまま流します。
• 中継した戻り先（redirect_uri）: 公開の HTTPS のエンドポイントがホストへ転送している場合（たとえば戻り先のポートに向けた Tailscale Funnel やリバースプロキシ）、oauth.redirect_uri を設定すれば、ブラウザの戻りがそのまま Hermes に届きます。トンネルも貼り付けも要りません。

mcp_servers:
  myserver:
    url: "https://mcp.example.com/mcp"
    auth: oauth
    oauth:
      redirect_port: 8765                                # fixed port for the proxy to target
      redirect_uri: "https://oauth.example.ts.net/callback"

完全に画面の無いゲートウェイ（メッセージのボットで、対話できる端末がまったく無い場合）では、任意で入れられる mcp-oauth-remote-gateway スキル が、手順を自分でこなしてトークンを Hermes の期待する場所に書くところまで、エージェントを導いてくれます。

落とし穴 — WAF が 127.0.0.1 の戻り先を拒否する。 認可サーバーの前に WAF を置いていて、クエリ文字列に 127.0.0.1 がそのまま含まれる認可の要求を 403 にしてしまう提供元がいくつかあります（Reclaim.ai の AWS API Gateway が知られた例で、OAuth アプリに届く前にすべて {"message":"Forbidden"} が返ります）。oauth.redirect_host: localhost を設定して http://localhost:<port>/callback を使ってください。どちらにしても、戻りを待ち受ける側は 127.0.0.1 に結びついたままです。

DCR に対応しないサーバー（Slack など）、あらかじめ登録した client_id と client_secret、権限の範囲の調整、hermes mcp login <server> での再認証まで含めた通しの手順は、SSH 越し / リモートホストでの OAuth を参照してください。

落とし穴 — 自動登録に対応しない提供元（Google Drive、Atlassian）。 素の auth: oauth が頼っている動的クライアント登録の手順（RFC 7591）を拒否するサーバーがあります。Google 公式の Drive のサーバー（https://drivemcp.googleapis.com/mcp/v1）は 400 Bad Request を返すので、OAuth のクライアントは作られず、トークンも手に入りません。症状は分かりにくく、こうしたサーバーは認証なしでも tools/list に応えるため、hermes mcp login がツールを並べてうまくいったように見えてしまいます。しかし、あとで実際にツールを呼ぶと必ず時間切れになります。いまの hermes mcp login はこれを検出し（トークンが本当にディスクに落ちたかを確かめます）、自分の OAuth クライアントを用意するよう伝えます。提供元の管理画面で作って、設定に足してください。

mcp_servers:
  googledrive:
    url: "https://drivemcp.googleapis.com/mcp/v1"
    auth: oauth
    oauth:
      client_id: "<your-oauth-client-id>"
      client_secret: "<your-oauth-client-secret>"

そのうえで hermes mcp login googledrive を実行します。あらかじめ登録したクライアントがあるので、Hermes は登録の手順を飛ばし、通常のブラウザでの認可を進めます。

落とし穴 — 設定の自動再読み込みとの競合。 Hermes のセッションを動かしたまま ~/.hermes/config.yaml を編集すると、CLI は 30 秒の制限時間で MCP の接続を読み直します。対話式の OAuth の手順には、これでは足りません。項目を足したら、別の端末から hermes mcp login <server> を実行してください。こちらは認証を終えるのを 5 分まで待ちます。

mTLS とクライアント証明書

相互 TLS（クライアント証明書による認証）を求めるリモートの HTTP MCP サーバーには、client_cert と client_key で対応します。Hermes は解決した証明書を、TLS の握手のために下位の HTTP クライアントへ渡します。

client_cert は三つの形を受け付けます。

• 一つにまとめた PEM のパス — 証明書と秘密鍵の両方を持つ一つのファイルです。

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/.certs/mcp-client.pem"

• [cert, key] の 2 要素 — 証明書と鍵が別のファイルにある場合です（client_cert と client_key を設定するのと同じです）。

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key"]

• [cert, key, password] の 3 要素 — 秘密鍵が暗号化されている場合で、三つめが鍵の合言葉です。

mcp_servers:
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: ["~/.certs/mcp-client.crt", "~/.certs/mcp-client.key", "${MCP_KEY_PASSWORD}"]

client_cert（まとめた PEM）と、明示的な client_key を使って、証明書と鍵を完全に分けたままにもできます。パスは ~ の展開に対応しています。ファイルが無い場合は、意味の分からない TLS の握手の失敗ではなく、どのサーバーの話かが分かるはっきりしたエラーになります。

利用者ごとの識別ヘッダー

呼び出し元の識別によって振る舞いを変えるリモートの HTTP / SSE の MCP サーバー（利用者ごとの回数制限、監査の記録、複数の顧客の振り分けなど）には、identity_header を使って毎回の要求に識別のヘッダーを付けられます。

mcp_servers:
  team_api:
    url: "https://mcp.team.example.com/mcp"
    identity_header:
      name: "X-User-Id"
      value_from: "static"   # "static" (default) or "profile"
      value: "alice"         # required for static

• value_from: static は、config.yaml に書いた value をそのまま送ります。
• value_from: profile は、いま動いている Hermes のプロファイル名を、接続時に一度だけ解決して送ります。一つの機械にある複数のプロファイルが同じサーバーと話していて、サーバー側で見分けたいときに便利です。

サーバーの headers に同じ名前（大文字と小文字は問いません）の項目が明示されていれば、常にそちらが勝ちます。識別のヘッダーが、あなたのヘッダーの設定を上書きすることはありません。identity_header の書き方が正しくない場合は、警告のうえ無視されます。それでサーバーへの接続が止まることはありません。stdio のサーバーでは、この項目は警告とともに無視されます（stdio にはヘッダーがありません）。

設定の基本項目

Hermes は ~/.hermes/config.yaml の mcp_servers の下から MCP の設定を読みます。

よく使う項目

stdio の最小の例

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

メモリを多く使う stdio のサーバーを作り直す

ブラウザを使う MCP サーバー（たとえば @playwright/mcp）は、最初にツールを 呼んだあと Chromium をまるごと常駐させます。数百 MB が解放されないままです。 自動での作り直しを有効にすると、放置の時間や寿命の上限を過ぎたところでサーバーは 畳まれ、次にそのツールが呼ばれたときに裏で立ち上がり直します（その間もツールは 登録されたままです）。

mcp_servers:
  playwright:
    command: "npx"
    args: ["-y", "@playwright/mcp@latest", "--headless"]
    idle_timeout_seconds: 900     # recycle after 15 min without a tool call
    max_lifetime_seconds: 86400   # and at least once a day regardless

HTTP の最小の例

mcp_servers:
  company_api:
    url: "https://mcp.internal.example.com"
    headers:
      Authorization: "Bearer ***"

内蔵の定型設定

よく知られた MCP サーバーについては、hermes mcp add に --preset を渡すと、通信の詳細が埋まるので、コマンドや引数を調べる必要がありません。定型設定が与えるのは既定値だけなので、同じコマンドラインで渡した他のもの（環境変数、ヘッダー、絞り込み）はそのまま優先されます。

# Add Codex CLI as an MCP server in one line
hermes mcp add codex --preset codex

これは、次と同じ内容を書き込みます。

mcp_servers:
  codex:
    command: "codex"
    args: ["mcp-server"]

手元での名前は自由に付けられます（hermes mcp add my-codex --preset codex でも構いません）。定型設定が与えるのは command と args の既定値だけです。

Hermes は MCP のツールをどう登録するか

Hermes は、内蔵のツール名とぶつからないように、MCP のツールに接頭辞を付けます。

mcp_<server_name>_<tool_name>

例:

実際のところ、接頭辞の付いた名前を自分で呼ぶ必要はほとんどありません。Hermes はそのツールを認識し、普通に考えながら選びます。

ツールの結果の掃除と _meta

モデルが目にする前に、すべての MCP のツールの結果に対して二つのことが行われます。

• 見えない Unicode の TAG 文字が取り除かれます。 U+E0000〜U+E007F の範囲の文字は、端末やチャットの画面では何も表示されないのに、モデルには完全に見えています。悪意のある、あるいは乗っ取られたサーバーが、プロンプトインジェクションを忍び込ませる古典的な経路です。Hermes はこれを、ツールの結果、リソースの内容、ツールの説明から取り除きます。正当な絵文字のタグの並び（🏴󠁧󠁢󠁳󠁣󠁴󠁿 のような地域の旗）はそのまま残ります。
• 提供元の _meta は渡し、プロトコルが予約している鍵は渡しません。 サーバーがツールの結果に _meta の対応表を付けている場合（com.example/handoff のような提供元の名前空間）、Hermes はそれを結果の内容とともにモデルへ渡します。プロトコルが予約している接頭辞の下にある鍵、つまり modelcontextprotocol か mcp というラベルにさらにラベルが続くもの、たとえば modelcontextprotocol.io/... や tools.mcp.com/... は、MCP の仕様の鍵の名前の規則に従って落とされます。モデルに見せるものが何も残らなければ、_meta の項目自体が省かれます。

MCP の補助ツール

サーバーが対応していれば、Hermes は MCP のリソースとプロンプトを扱う補助ツールも登録します。

• list_resources
• read_resource
• list_prompts
• get_prompt

これらはサーバーごとに、同じ接頭辞の形で登録されます。たとえば次のようになります。

• mcp_github_list_resources
• mcp_github_get_prompt

大切な点

これらの補助ツールは、いまはサーバーの能力を見て登録されます。

• MCP のセッションが実際にリソースの操作に対応しているときだけ、リソース向けの補助ツールを登録します
• MCP のセッションが実際にプロンプトの操作に対応しているときだけ、プロンプト向けの補助ツールを登録します

そのため、呼べるツールはあってもリソースやプロンプトを持たないサーバーには、これらの包みは付きません。

サーバーごとの絞り込み

それぞれの MCP サーバーが Hermes にどのツールを提供するかを決められるので、ツールの名前の空間を細かく管理できます。

サーバーをまるごと無効にする

mcp_servers:
  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

enabled: false なら、Hermes はそのサーバーを完全に飛ばし、接続すら試みません。

サーバーのツールを許可する形で選ぶ

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

その MCP サーバーのツールのうち、挙げたものだけが登録されます。

include と exclude の項目には、グロブの型（*、?、[...]。大文字と小文字は 区別します）も書けます。include: ["*_dns_*"] と書けば、名前に _dns_ を含む ツールがすべて登録されます。特殊な文字を含まない項目は、これまでどおり完全一致です。 自動生成のエンドポイントのツールを何千個も出すサーバーを、製品の系統ごとに絞り込むには、 グロブが現実的な手立てです。

サーバーのツールを拒否する形で選ぶ

mcp_servers:
  stripe:
    url: "https://mcp.stripe.com"
    tools:
      exclude: [delete_customer]

除いたもの以外、そのサーバーのツールはすべて登録されます。

グロブの型

どちらの並びも、正確な名前に加えて fnmatch 風のグロブを受け付けます。Cloudflare の API の MCP（?codemode=false でおよそ 3,300 個のツール）のように、平たく巨大な ものでは、製品の領域をエンドポイント一つずつ除いていくのは現実的ではないので、 これが欠かせません。

mcp_servers:
  cloudflare:
    url: "https://mcp.cloudflare.com/mcp?codemode=false"
    auth: oauth
    tools:
      exclude: ["*_radar_*", "*_accounts_dlp_*", "*_zones_web3_*"]

グロブの特殊な文字（*、?、[）を含まない項目は完全一致です。docs は docs という名前のツールだけを除き、docs_search は決して除きません。

優先の規則

両方が書かれている場合は、次のようになります。

tools:
  include: [create_issue]
  exclude: [create_issue, delete_issue]

include が勝ちます。

補助ツールも絞り込む

Hermes が足す補助的な包みだけを、別に無効にすることもできます。

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

つまり、次のようになります。

• tools.resources: false は list_resources と read_resource を無効にします
• tools.prompts: false は list_prompts と get_prompt を無効にします

すべてを盛り込んだ例

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

  stripe:
    url: "https://mcp.stripe.com"
    headers:
      Authorization: "Bearer ***"
    tools:
      exclude: [delete_customer]
      resources: false

  legacy:
    url: "https://mcp.legacy.internal"
    enabled: false

すべて絞り込まれてしまったらどうなるか

設定で呼べるツールがすべて除かれ、対応している補助ツールもすべて無効か省かれている場合、Hermes はそのサーバーのために空のツール群を作りません。

そのおかげで、ツールの一覧がすっきり保たれます。

実行時の動き

いつ見つけるか

Hermes は起動時に MCP のサーバーを見つけ、そのツールを通常のツールの登録簿に加えます。

ツールの動的な発見

MCP のサーバーは、動作中に使えるツールが変わったとき、notifications/tools/list_changed の通知を送って Hermes に知らせられます。この通知を受け取ると、Hermes は自動でそのサーバーのツールの一覧を取り直し、登録簿を更新します。手作業の /reload-mcp は要りません。

これは、能力が動的に変わる MCP サーバーに便利です（たとえば、新しいデータベースの構造が読み込まれるとツールが増えるサーバーや、サービスが落ちるとツールが減るサーバーです）。

取り直しはロックで守られているので、同じサーバーから通知が立て続けに来ても、取り直しが重なることはありません。プロンプトとリソースの変更の通知（prompts/list_changed、resources/list_changed）は受け取りますが、まだ対応する動きはしていません。

読み直す

MCP の設定を変えたら、次を使ってください。

/reload-mcp

これで設定から MCP のサーバーを読み直し、使えるツールの一覧が更新されます。サーバー自身が動作中にツールの変更を送ってくる場合については、上の ツールの動的な発見 を参照してください。

ツール群

設定した MCP サーバーは、登録されたツールを一つ以上提供していれば、実行時のツール群も作ります。

mcp-<server>

これで、MCP のサーバーをツール群の単位で考えやすくなります。

セキュリティの考え方

stdio の環境変数の絞り込み

stdio のサーバーに対して、Hermes はあなたのシェルの環境をそのまま丸ごと渡したりはしません。

明示的に設定した env と、安全な最小限のものだけが渡されます。これで、秘密がうっかり漏れることを減らせます。

設定による見せ方の管理

新しい絞り込みの仕組みは、セキュリティの手立てでもあります。

• モデルに見せたくない危ないツールを無効にする
• 機微なサーバーについては、最小限の許可の一覧だけを出す
• その面を見せたくないときは、リソースとプロンプトの包みを無効にする

使い方の例

issue の管理だけに絞った GitHub のサーバー

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

こんなふうに使います。

Show me open issues labeled bug, then draft a new issue for the flaky MCP reconnection behavior.

危ない操作を外した Stripe のサーバー

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

こんなふうに使います。

Look up the last 10 failed payments and summarize common failure reasons.

プロジェクト一つに絞ったファイルシステムのサーバー

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

こんなふうに使います。

Inspect the project root and explain the directory layout.

困ったときは

MCP のサーバーにつながらない

確かめること:

# Verify MCP deps are installed (already included in standard install)
cd ~/.hermes/hermes-agent && uv pip install -e ".[mcp]"

node --version
npx --version

そのうえで設定を見直し、Hermes を再起動してください。

ツールが現れない

考えられる原因は次のとおりです。

• サーバーへの接続に失敗した
• 発見に失敗した
• 絞り込みの設定でそのツールが除かれていた
• そのサーバーに、その補助的な能力が無い
• enabled: false でサーバーが無効になっている

意図して絞り込んでいるなら、それが正しい結果です。

リソースやプロンプトの補助ツールが現れないのはなぜか

いまの Hermes は、次の二つがどちらも満たされたときにだけ、それらの包みを登録するからです。

1. 設定が許している
2. サーバーのセッションが実際にその能力に対応している

これは意図した動きで、ツールの一覧を正直に保つためのものです。

ツールの並列呼び出し

既定では、MCP のツールは一つずつ順番に動きます。同時に動かしても安全なツールを MCP サーバーが出しているなら（たとえば読み取りだけの問い合わせや、互いに独立した API の呼び出し）、並列の実行を選べます。

mcp_servers:
  docs:
    command: "docs-server"
    supports_parallel_tool_calls: true

supports_parallel_tool_calls が true のとき、Hermes はそのサーバーの複数のツールを、一回のツール呼び出しのまとまりの中で同時に実行することがあります。内蔵の読み取り専用のツール（web_search、read_file など）と同じ扱いです。

MCP のサンプリング対応

MCP のサーバーは、sampling/createMessage のプロトコルを通して、Hermes に LLM の推論を頼めます。これにより MCP のサーバーは、自分の代わりに文章を作ってほしいと Hermes に依頼できます。LLM の力は必要だけれど自前のモデルを持たないサーバーに便利です。

サンプリングは、すべての MCP サーバーで 既定で有効 です（MCP の SDK が対応している場合）。サーバーごとの設定は sampling の下に書きます。

mcp_servers:
  my_server:
    command: "my-mcp-server"
    sampling:
      enabled: true            # Enable sampling (default: true)
      model: "openai/gpt-4o"  # Override model for sampling requests (optional)
      max_tokens_cap: 4096     # Max tokens per sampling response (default: 4096)
      timeout: 30              # Timeout in seconds per request (default: 30)
      max_rpm: 10              # Rate limit: max requests per minute (default: 10)
      max_tool_rounds: 5       # Max tool-use rounds in sampling loops (default: 5)
      allowed_models: []       # Allowlist of model names the server may request (empty = any)
      log_level: "info"        # Audit log level: debug, info, or warning (default: info)

サンプリングを受け持つ部分には、時間の窓をずらしながら数える回数制限、要求ごとの制限時間、ツールの繰り返しの深さの上限があり、使いすぎを防ぎます。件数・エラー・使ったトークンといった数値は、サーバーの実体ごとに記録されます。

特定のサーバーでサンプリングを止めるには、次のようにします。

mcp_servers:
  untrusted_server:
    url: "https://mcp.example.com"
    sampling:
      enabled: false

MCP の問い合わせ（elicitation）対応

MCP のサーバーは、elicitation/create のプロトコル（mcp の Python SDK 1.11.0 以降）を通して、ツールの実行の途中で、決まった形の入力を利用者に尋ねられます。Hermes は フォーム形式 の問い合わせを、いまある承認の窓口へ流します。CLI や TUI では対話的な確認、Telegram や Slack などゲートウェイのプラットフォームでは承認のボタンです。だから、セッションがどこにあっても要求はあなたに届きます。URL 形式 の問い合わせ（サーバーが外部の URL を示すもの）は、対応していないものとして断ります。

問い合わせは、サーバーごとに 既定で有効 です。設定は elicitation の下に書きます。

mcp_servers:
  my_server:
    command: "my-mcp-server"
    elicitation:
      enabled: true    # default: true
      timeout: 300     # seconds to wait for your answer (default: 300)

既定の 5 分という制限時間は、ゲートウェイの承認の既定に合わせたものです。すぐには見られない場所にいる利用者でも、サーバーがあきらめる前に答えられます。サーバーごとの数値（要求、承認、拒否、エラー）は、受け持つ部分で記録されます。

Hermes を MCP サーバーとして動かす

MCP サーバーに つなぐ だけでなく、Hermes 自身が MCP サーバーに なる こともできます。これにより、MCP を扱える他のエージェント（Claude Code、Cursor、Codex、その他どんな MCP のクライアントでも）が、Hermes のメッセージ機能を使えます。会話の一覧、履歴の読み取り、そしてつながっているすべてのプラットフォームへのメッセージ送信です。

どんなときに使うか

• Claude Code、Cursor、その他のコーディングのエージェントに、Hermes を通して Telegram / Discord / Slack のメッセージを送り書きさせたい
• Hermes につながっているメッセージのプラットフォームすべてに、一つの MCP サーバーで橋を架けたい
• すでにプラットフォームがつながった Hermes のゲートウェイが動いている

手早く始める

hermes mcp serve

これで stdio の MCP サーバーが立ち上がります。プロセスの面倒を見るのは、あなたではなく MCP のクライアントです。

MCP のクライアント側の設定

MCP のクライアントの設定に Hermes を足します。たとえば Claude Code の ~/.claude/claude_desktop_config.json では次のようになります。

{
  "mcpServers": {
    "hermes": {
      "command": "hermes",
      "args": ["mcp", "serve"]
    }
  }
}

Hermes を特定の場所にインストールしている場合は、次のようになります。

{
  "mcpServers": {
    "hermes": {
      "command": "/home/user/.hermes/hermes-agent/venv/bin/hermes",
      "args": ["mcp", "serve"]
    }
  }
}

使えるツール

この MCP サーバーは 10 個のツールを出します。OpenClaw のチャンネルの橋渡しと同じ範囲に、Hermes 独自のチャンネル閲覧を加えたものです。

できごとの仕組み

この MCP サーバーには、Hermes のセッションのデータベースを見て新しいメッセージを拾う、生きた橋渡しが入っています。これで MCP のクライアントは、届いた会話をほぼその場で知ることができます。

# Poll for new events (non-blocking)
events_poll(after_cursor=0)

# Wait for next event (blocks up to timeout)
events_wait(after_cursor=42, timeout_ms=30000)

できごとの種類は、message、approval_requested、approval_resolved です。

できごとの待ち行列はメモリの上にあり、橋渡しがつながった時点から始まります。それより前のメッセージは messages_read から取れます。

起動時の指定

hermes mcp serve              # Normal mode
hermes mcp serve --verbose    # Debug logging on stderr

仕組み

この MCP サーバーは、会話のデータを Hermes のセッションの保管庫から直接読みます。主となるのは ~/.hermes/state.db で、sessions.json は古い形式のための予備としてだけ残しています。背後のスレッドがデータベースを見て新しいメッセージを拾い、メモリ上のできごとの待ち行列を保ちます。メッセージの送信には、cron の配送や hermes send の CLI を支えているのと同じ内部の送信の仕組み（tools/send_message_tool.py）を使います。

読み取りの操作（会話の一覧、履歴の読み取り、できごとの取得）では、ゲートウェイが動いている必要はありません。送信の操作では動いている必要があります。プラットフォームのアダプターに生きた接続が要るからです。

いまの制限

• 組み込みの hermes mcp serve が出すのは、いまのところ stdio だけ の MCP サーバーです。HTTP の MCP サーバーが必要なら、別に橋渡しを走らせるか、もっとよくある選択として、すでに stdio と HTTP の両方を話せる Hermes の MCP の クライアント 側を使ってください（mcp_servers.yaml や config.yaml の url と headers。上の HTTP サーバー を参照）。
• できごとの取得は、更新時刻を見て無駄を省いたデータベースの確認により、およそ 200 ミリ秒ごとに行われます（ファイルが変わっていなければ何もしません）
• claude/channel の通知を押し出すプロトコルには、まだ対応していません
• 送れるのは文字だけです（messages_send から動画や添付は送れません）

関連する文書

• Hermes で MCP を使う
• CLI のコマンド一覧
• スラッシュコマンド一覧
• よくある質問