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 リポジトリ、ローカルデータベース)への低遅延アクセスが必要な場合。
例
# 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 インターフェースがある場合。
例
# 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-RPC | HTTP リクエスト |
| ライフサイクル | 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つのステップを実行します:
- 設定ガイド: API キーの入力を促すか、OAuth ブラウザ認可フローを案内します
- ツール検出: サーバーに接続し、公開されている完全なツールリストを取得します
- ツール選択: ツールリストを表示し、有効にするツールを選択させます(デフォルトではすべて選択)
3番目のステップ(ツール選択)は重要なセキュリティ段階です。すべてのツールが必要なわけではありません。たとえば GitHub サーバーが delete_repo を公開している場合、不要であればチェックを外せます。
ツールフィルタリング:必要なものだけを公開する
すべての MCP サーバーは、細かいツールフィルタリングをサポートしています。これは Agent の攻撃対象領域を減らすための重要なセキュリティメカニズムです。
include モード(ホワイトリスト)
リスト内のツールのみを登録し、それ以外はすべて除外します:
例
# 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 モード(ブラックリスト)
リスト内のツールを除外し、それ以外をすべて登録します:
例
# 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 サーバーはツールに加えて、リソースやプロンプトを公開する場合もあります。不要であれば、無効化できます:
例
# プラットフォーム設定で 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:ブロック内で明示的に宣言された変数のみが子プロセスに渡されます:
例
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 互換サーバーを手動で追加することもできます。
例
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 ヘッダーを確認し、ネットワーク接続を確認 |