Hermes Agent MCP 統合

MCP(Model Context Protocol)は Anthropic が提唱するオープンプロトコルであり、LLM と外部ツールの相互作用を標準化するために使用されます。

Hermes は MCP をネイティブサポートしており、コアコードを変更することなく、GitHub、データベース、ファイルシステム、ブラウザスタック、内部 API など、あらゆる MCP 互換サービスに接続できます。

この章では、MCP の2つの接続方法、ツールフィルタリング戦略、安全分離メカニズム、一般的な問題のトラブルシューティングについて詳しく説明します。


MCP とは

MCP は実際の問題を解決します: 新しいサービスに接続するたびに、従来の方法ではアダプタコードを作成し、ツールスキーマを定義し、認証を処理する必要がありました。つまり、各サービスごとに使い捨ての作業が必要でした。

MCP はこれらを標準化しました。MCP プロトコルを実装するあらゆるサービスに、Hermes は追加開発なしで直接接続できます。

MCP の中心的な役割:

Hermes Agent(MCP 客户端)
    │
    ├── stdio ──→ MCP 服务器 A(本地子进程)
    │                  └── 暴露工具:git_commit, git_push...
    │
    ├── HTTP ───→ MCP 服务器 B(远程服务)
    │                  └── 暴露工具:list_issues, create_issue...
    │
    └── HTTP ───→ MCP 服务器 C(远程 OAuth)
                       └── 暴露工具:search_docs, create_page...

標準インストールには MCP サポートが含まれています、追加の手順は不要です。すべての MCP サーバーは~/.hermes/config.yamlで一元的に設定されます。

MCP は Hermes 独自のプロトコルではありません。オープンです。他の MCP 対応ツール用に作成されたサーバー(Claude Code の MCP サーバーなど)は Hermes で直接使用でき、その逆も同様です。


2種類のMCPサーバータイプ

ローカル stdio サーバー

子プロセスとしてローカルで実行され、標準入力/出力(stdin/stdout)を介して Hermes と通信します。

通信には JSON-RPC プロトコルを使用し、各メッセージは改行文字で区切られます。

適用シナリオ: ツールがローカルにインストールされており、ローカルリソース(ファイルシステム、Git リポジトリ、ローカルデータベース)への低遅延アクセスが必要な場合。

例

# ファイルパス: ~/.hermes/config.yaml
# MCP stdio サーバー設定
mcp_servers
:
 # GitHub サーバー: npx で起動
  github
:
    command
: "npx"
    args
: ["-y", "@modelcontextprotocol/server-github"]
    env
:
      GITHUB_PERSONAL_ACCESS_TOKEN
: "ghp_..."

  # ファイルシステムサーバー: Agent のアクセス範囲を制限
  filesystem
:
    command
: "npx"
    args
:
     - "-y"
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/projects"     # このディレクトリへのアクセスのみ許可

  # Git サーバー: uvx で起動
  git
:
    command
: "uvx"
    args
:
     - "mcp-server-git"
      - "--repository"
      - "/home/user/project"

stdio サーバーのライフサイクルは Hermes によって管理されます:

  • セッションの開始または/reload-mcp時に、Hermes は子プロセスを起動します
  • セッションの終了またはサーバーの無効化時に、Hermes は子プロセスを終了します
  • 子プロセスがクラッシュすると自動的に再起動します(最大3回再試行)

リモート HTTP サーバー

HTTP リクエストを介してリモート MCP エンドポイントに直接接続し、複数の認証方式をサポートします。

適用シナリオ: ツールがリモートでホストされている場合、または組織内に既存の MCP インターフェースがある場合。

例

# ファイルパス: ~/.hermes/config.yaml
# MCP HTTP サーバー設定
mcp_servers
:
 # 方法1: 静的 Bearer Token 認証
  internal_api
:
    url
: "https://mcp.internal.example.com/mcp"
    headers
:
      Authorization
: "Bearer ${MY_TOKEN}"    # 環境変数をサポート

  # 方法2: OAuth 2.1 認証(Linear、Sentry、Figma、Stripe など)
  linear
:
    url
: "https://mcp.linear.app/mcp"
    auth
: oauth

  # 方法3: OAuth クライアントの事前登録が必要なプロバイダー
  googledrive
:
    url
: "https://drivemcp.googleapis.com/mcp/v1"
    auth
: oauth
    oauth
:
      client_id
: "<your-oauth-client-id>"       # 事前登録して取得
      client_secret
: "<your-oauth-client-secret>"

2種類の比較

観点stdio サーバーHTTP サーバー
実行場所ローカル(子プロセス)リモート(独立したサービス)
通信方法stdin/stdout + JSON-RPCHTTP リクエスト
ライフサイクルHermes が起動/停止を管理Hermes から独立
遅延極めて低い(プロセス内通信)ネットワーク遅延による
認証環境変数で渡すBearer Token / OAuth 2.1
典型的なシナリオローカル Git、ファイルシステム、データベースGitHub API、Linear、Sentry
設定の複雑さ低い(1行のコマンド)中(URL + 認証の設定が必要)

Nous 厳選 MCP ディレクトリ

Hermes には、Nous Research の審査を経た MCP ディレクトリが組み込まれており、ワンクリックインストールを提供します。

閲覧とインストール

インタラクティブセレクタ(TUI)を開いて、すべてのディレクトリエントリを閲覧します:

hermes mcp

その他のコマンド:

# 纯文本列表(适合脚本化)
hermes mcp catalog

# 按名称一键安装
hermes mcp install n8n
hermes mcp install github
hermes mcp install linear

インタラクティブセレクタは各エントリの現在の状態を表示します:

n8n          available              管理和检查 n8n 工作流
linear       enabled                Linear 问题/项目管理(远程 OAuth)
github       installed (disabled)   GitHub 仓库 + PR 工具
filesystem   installed (enabled)    安全的文件系统操作
postgres     available               PostgreSQL 数据库查询
slack        available               Slack 消息和频道管理

状態の説明:

状態意味
availableインストール可能、未インストール
installed (enabled)インストール済みかつ有効、Agent が使用可能
installed (disabled)インストール済みだが無効、Agent は使用不可
enabledリモート OAuth サーバー、承認済みで有効

デスクトップ版では設定メニューで設定を確認します:

ダッシュボードでは左側の MCP メニューで設定を確認します:

インストールプロセスで何が起きるか

ワンクリックインストールは自動的に3つのステップを実行します:

  1. 設定ガイド: API キーの入力を促すか、OAuth ブラウザ認可フローを案内します
  2. ツール検出: サーバーに接続し、公開されている完全なツールリストを取得します
  3. ツール選択: ツールリストを表示し、有効にするツールを選択させます(デフォルトではすべて選択)

3番目のステップ(ツール選択)は重要なセキュリティ段階です。すべてのツールが必要なわけではありません。たとえば GitHub サーバーが delete_repo を公開している場合、不要であればチェックを外せます。


ツールフィルタリング:必要なものだけを公開する

すべての MCP サーバーは、細かいツールフィルタリングをサポートしています。これは Agent の攻撃対象領域を減らすための重要なセキュリティメカニズムです。

include モード(ホワイトリスト)

リスト内のツールのみを登録し、それ以外はすべて除外します:

例

# ファイルパス: ~/.hermes/config.yaml
# include ホワイトリストモード——最も安全な選択
mcp_servers
:
  github
:
    command
: "npx"
    args
: ["-y", "@modelcontextprotocol/server-github"]
    env
:
      GITHUB_PERSONAL_ACCESS_TOKEN
: "ghp_..."
    tools
:
      include
:
       - list_issues
        - create_issue
        - update_issue
        - search_code
      # これら4つ以外のツールは登録されません

exclude モード(ブラックリスト)

リスト内のツールを除外し、それ以外をすべて登録します:

例

# ファイルパス: ~/.hermes/config.yaml
# exclude ブラックリストモード——高リスク操作を除外
mcp_servers
:
  stripe
:
    url
: "https://mcp.stripe.com"
    headers
:
      Authorization
: "Bearer ${STRIPE_KEY}"
    tools
:
      exclude
:
       - delete_customer
        - refund_payment
        - create_live_key
      # これら3つ以外のツールはすべて登録されます

フィルタリングルールの優先順位

設定動作適用シナリオ
include のみinclude リスト内のツールのみを登録セキュリティ優先、最小権限の原則
exclude のみすべてのツールを登録し、exclude リストを除外利便性優先、少数の高リスク操作を除外
両方を設定include が優先され、exclude は無視される—
どちらも設定しないサーバーが公開するすべてのツールを登録その MCP サーバーを完全に信頼

リソースとプロンプトを無効化

MCP サーバーはツールに加えて、リソースやプロンプトを公開する場合もあります。不要であれば、無効化できます:

例

# ファイルパス:~/.hermes/config.yaml
# プラットフォーム設定で MCP ツールセットを参照
platform_toolsets:
  cli:
    - hermes-cli
    - file
    - terminal
- mcp-github # GitHub MCP ツール
- mcp-linear # Linear MCP ツール

  telegram:
    - hermes-gateway
- mcp-github # Telegram でも GitHub ツールを有効化

  discord:
    - hermes-gateway
# Discord では GitHub ツールを有効化しない(セキュリティポリシー)

MCP 環境変数の分離

これは Hermes の MCP セキュリティ機構の中で最も見落とされがちですが、最も重要な設計です。

MCP stdio 子プロセスはフィルタリングされた環境を受け取り、デフォルトでは以下の変数のみが渡されます:

PATH, HOME, USER, LANG, LC_ALL, TERM, SHELL, TMPDIR
以及所有 XDG_* 变量

他のすべての環境変数(API Key、Token、パスワード)はブロックされます。

MCP サーバー設定のenv:ブロック内で明示的に宣言された変数のみが子プロセスに渡されます:

例

    env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." # この変数のみが渡される
# Shell で GITHUB_TOKEN を export していても、
# ここで宣言しなければ MCP 子プロセスに渡されません

なぜこのような設計なのでしょうか?.env に 10 個の API Key(OpenAI、Anthropic、SerpAPI、Telegram Bot Token...)を保存していると仮定します。MCP サーバーがすべての環境変数を読み取れる場合、悪意のある MCP サーバーツールがすべての認証情報を盗む可能性があります。環境変数の分離により、明示的に宣言された変数だけしか見ることができません。

エラー情報の自動マスキング

MCP ツールのエラーメッセージは LLM に返す前に自動的にマスキングされます——機密情報(API Key、Token、パスワード)は置き換えられます[REDACTED]。

これにより、Agent がエラーを分析する際に平文の認証情報を誤って見ることが防止されます。


MCP サーバーを手動で追加

Nous ディレクトリからのワンクリックインストールに加えて、MCP 互換サーバーを手動で追加することもできます。

例

# stdio サーバーを手動で追加
hermes mcp add my-git-server \
  --command "uvx" \
  --args "mcp-server-git,--repository,/home/user/project"

# HTTP サーバーを手動で追加
hermes mcp add internal-db \
  --url "https://mcp.internal.example.com/db" \
  --header "Authorization: Bearer ${DB_TOKEN}"

# 接続が正常かテスト
hermes mcp test my-git-server

# ツールフィルターの設定
hermes mcp configure my-git-server

hermes mcp configureインタラクティブなツール選択画面が開き、有効にするツールを再選択できます。


MCP 設定の再読み込み

config.yaml の MCP 設定を変更した後、Agent 全体を再起動する必要はありません:

例

# ─── 閲覧とインストール ─────────────────────────────────────────────
hermes mcp # インタラクティブなカタログセレクター(TUI)
hermes mcp catalog # プレーンテキストのカタログ一覧
hermes mcp install <name> # カタログからワンクリックインストール

# ─── 手動管理 ───────────────────────────────────────────────
hermes mcp add <name> --command <cmd> --args <...> # stdio サーバーを追加
hermes mcp add <name> --url <url> # HTTP サーバーを追加
hermes mcp remove <name> # サーバー設定を削除
hermes mcp list # 設定済みのすべてのサーバーを一覧表示
hermes mcp test <name> # サーバー接続をテスト
hermes mcp configure <name> # 有効なツールを再選択

# ─── OAuth 認証 ─────────────────────────────────────────────
hermes mcp login <server> # OAuth 認可を開始(最大 5 分待機)

# ─── 実行時操作 ─────────────────────────────────────────────
/reload-mcp # セッション内で MCP 設定を再読み込み
hermes mcp reload # コマンドラインで再読み込み

よくある問題のトラブルシューティング

問題考えられる原因解決策
MCP ツールが表示されないサーバーが有効でない、または接続失敗hermes mcp list を実行して状態を確認し、hermes mcp test で接続をテスト
ツールフィルターが機能しないHermes 登録後のツール名を使用しているMCP の元のツール名に変更する(ハイフンを含む。例: list_issues ではなく list-issues)
stdio サーバーが頻繁にクラッシュする依存関係の欠落または権限不足command が PATH にあるか確認し、手動で実行してテスト
OAuth 認可がタイムアウト/reload-mcp の 30 秒では不十分先に hermes mcp login を実行し、完了後に /reload-mcp を実行
環境変数が機能しないenv: ブロック内で明示的に宣言されていないmcp_servers.<name>.env で宣言し、Shell の環境変数に依存しない
HTTP サーバーの接続が拒否されるURL に到達できない、または認証失敗URL と Authorization ヘッダーを確認し、ネットワーク接続を確認
その他の拡張