native-mcp

ネイティブ MCP クライアント

Hermes Agent には MCP サーバーに起動時に接続し、ツールを検出して、エージェントが直接呼び出せる第一級のツールとして利用できる組み込み MCP クライアントがあります。ブリッジ CLI は不要です。MCP サーバーのツールは、terminal や read_file などの組み込みツールと並んで表示されます。

使用する場面

次のような場合に使用してください。

• MCP サーバーに接続し、Hermes Agent 内からそのツールを使用する
• MCP を介して外部機能（ファイルシステムへのアクセス、GitHub、データベース、API）を追加する
• ローカルの stdio ベースの MCP サーバー（npx、uvx、または任意のコマンド）を実行する
• リモートの HTTP／StreamableHTTP MCP サーバーに接続する
• MCP ツールを自動検出し、すべての会話で利用できるようにする

設定を行わずに、ターミナルからその場限りの MCP ツール呼び出しを行う場合は、代わりに mcporter スキルを参照してください。

前提条件

• mcp Python package — オプションの依存関係です。pip install mcp でインストールしてください。インストールされていない場合、MCP サポートは通知なしで無効になります。
• Node.js — npx ベースの MCP サーバー（コミュニティサーバーの大半）に必要です
• uv — uvx ベースの MCP サーバー（Python ベースのサーバー）に必要です

MCP SDK をインストールします。

pip install mcp
# or, if using uv:
uv pip install mcp

クイックスタート

~/.hermes/config.yaml の mcp_servers キーの下に MCP サーバーを追加します。

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

Hermes Agent を再起動します。起動時に次の処理が行われます。

1. サーバーに接続します
2. 利用可能なツールを検出します
3. プレフィックス mcp_time_* を付けて登録します
4. すべてのプラットフォームのツールセットに挿入します

これで、現在の時刻を取得するようエージェントに尋ねるだけで、ツールを自然に使用できます。

設定リファレンス

mcp_servers の各エントリーは、サーバー名とその設定の組み合わせです。トランスポートの種類は stdio（コマンドベース）と HTTP（URL ベース）の 2 種類です。

Stdio トランスポート（command + args）

mcp_servers:
  server_name:
    command: "npx"             # (required) executable to run
    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
    env:                       # (optional) environment variables for the subprocess
      SOME_API_KEY: "value"
    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

HTTP トランスポート（url）

mcp_servers:
  server_name:
    url: "https://my-server.example.com/mcp"   # (required) server URL
    headers:                                     # (optional) HTTP headers
      Authorization: "Bearer sk-..."
    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60

すべての設定オプション

オプション	型	デフォルト	説明
command	string	--	実行する実行可能ファイル（stdio トランスポートでは必須）
args	list	[]	コマンドに渡す引数
env	dict	{}	サブプロセスに追加する環境変数
url	string	--	サーバーの URL（HTTP トランスポートでは必須）
headers	dict	{}	すべてのリクエストに付加する HTTP ヘッダー
timeout	int	120	ツール呼び出しごとのタイムアウト（秒）
connect_timeout	int	60	初回の接続と検出のタイムアウト

注：サーバー設定には command（stdio）か url（HTTP）のどちらか一方を指定する必要があり、両方は指定できません。

仕組み

起動時の検出

Hermes Agent の起動時に、ツールの初期化中に discover_mcp_tools() が呼び出されます。

1. ~/.hermes/config.yaml から mcp_servers を読み込みます
2. 各サーバーへの接続を、専用のバックグラウンドイベントループで開始します
3. MCP セッションを初期化し、list_tools() を呼び出して利用可能なツールを検出します
4. 各ツールを Hermes のツールレジストリに登録します

ツールの命名規則

MCP ツールは、次の命名パターンで登録されます。

mcp_{server_name}_{tool_name}

LLM API との互換性を確保するため、名前に含まれるハイフンとピリオドはアンダースコアに置き換えられます。

例：

• サーバー filesystem、ツール read_file → mcp_filesystem_read_file
• サーバー github、ツール list-issues → mcp_github_list_issues
• サーバー my-api、ツール fetch.data → mcp_my_api_fetch_data

自動挿入

検出後、MCP ツールはすべての hermes-* プラットフォームのツールセット（CLI、Discord、Telegram など）に自動で挿入されます。これにより、追加設定なしで、すべての会話で MCP ツールを利用できます。

接続のライフサイクル

• 各サーバーは、バックグラウンドのデーモンスレッドで長時間実行される asyncio タスクとして動作します
• 接続はエージェントプロセスの実行中、維持されます
• 接続が切断されると、指数バックオフによる自動再接続が開始されます（最大5回再試行し、バックオフは最大60秒です）
• エージェントのシャットダウン時には、すべての接続が正常に閉じられます

冪等性

discover_mcp_tools() は冪等です。複数回呼び出しても、接続されていないサーバーにのみ接続します。接続に失敗したサーバーは、以降の呼び出しで再試行されます。

トランスポートの種類

Stdio トランスポート

最も一般的なトランスポートです。Hermes は MCP サーバーをサブプロセスとして起動し、stdin/stdout 経由で通信します。

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

サブプロセスには、env で指定した変数に加えて、フィルタリングされた環境変数が引き継がれます（以下の「セキュリティ」セクションを参照）。

HTTP / StreamableHTTP トランスポート

リモートまたは共有の MCP サーバー向けです。mcp パッケージに HTTP クライアントのサポート（mcp.client.streamable_http）が含まれている必要があります。

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

インストール済みの mcp のバージョンで HTTP がサポートされていない場合、サーバーは ImportError で失敗し、ほかのサーバーは通常どおり動作を続けます。

セキュリティ

環境変数のフィルタリング

Stdio サーバーの場合、Hermes はシェル環境全体を MCP サブプロセスに渡しません。安全な基本環境変数のみが引き継がれます。

• PATH、HOME、USER、LANG、LC_ALL、TERM、SHELL、TMPDIR
• 任意の XDG_* 変数

それ以外の環境変数（API キー、トークン、シークレット）は、env 設定キーで明示的に追加しない限り除外されます。これにより、信頼できない MCP サーバーへの認証情報の意図しない漏えいを防ぎます。

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      # Only this token is passed to the subprocess
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."

エラーメッセージ内の認証情報の除去

MCP ツールの呼び出しが失敗した場合、エラーメッセージ内の認証情報と思われるパターンは、自動的に伏せ字にしてから LLM に表示されます。対象は次のとおりです。

• GitHub PAT（ghp_...）
• OpenAI 形式のキー（sk-...）
• Bearer トークン
• 一般的な token=、key=、API_KEY=、password=、secret= のパターン

トラブルシューティング

「MCP SDK not available -- skipping MCP tool discovery」

mcp Python パッケージがインストールされていません。インストールしてください。

pip install mcp

「No MCP servers configured」

~/.hermes/config.yaml に mcp_servers キーがないか、空になっています。サーバーを1つ以上追加してください。

「Failed to connect to MCP server 'X'」

よくある原因：

• コマンドが見つからない：command バイナリが PATH にありません。npx、uvx、または該当するコマンドがインストールされていることを確認してください。
• パッケージが見つからない：npx サーバーの場合、npm パッケージが存在しないか、自動インストールのために引数に -y が必要な可能性があります。
• タイムアウト：サーバーの起動に時間がかかりすぎています。connect_timeout を増やしてください。
• ポートの競合：HTTP サーバーの場合、URL に到達できない可能性があります。

「MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available」

お使いの mcp パッケージのバージョンには HTTP クライアントのサポートが含まれていません。アップグレードしてください。

pip install --upgrade mcp

ツールが表示されない

• サーバーが mcp_servers の下に記載されていることを確認してください（mcp や servers ではありません）
• YAML のインデントが正しいことを確認してください
• Hermes Agent の起動ログで接続メッセージを確認してください
• ツール名には mcp_{server}_{tool} というプレフィックスが付くため、このパターンを探してください

接続が頻繁に切断される

クライアントは指数バックオフ（1秒、2秒、4秒、8秒、16秒。最大60秒）で最大5回再試行します。サーバーに根本的に到達できない場合は、5回の試行後に再試行を中止します。サーバープロセスとネットワーク接続を確認してください。

例

Time Server（uvx）

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

mcp_time_get_current_time などのツールが登録されます。

Filesystem Server（npx）

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

mcp_filesystem_read_file、mcp_filesystem_write_file、mcp_filesystem_list_directory などのツールが登録されます。

認証付き GitHub Server

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

mcp_github_list_issues、mcp_github_create_pull_request などのツールが登録されます。

リモート HTTP サーバー

mcp_servers:
  company_api:
    url: "https://mcp.mycompany.com/v1/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
      X-Team-Id: "engineering"
    timeout: 180
    connect_timeout: 30

複数のサーバー

mcp_servers:
  time:
    command: "uvx"
    args: ["mcp-server-time"]

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

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

  company_api:
    url: "https://mcp.internal.company.com/mcp"
    headers:
      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
    timeout: 300

すべてのサーバーのツールが登録され、同時に利用可能になります。衝突を避けるため、各サーバーのツールにはサーバー名がプレフィックスとして付けられます。

サンプリング（サーバー起点のLLMリクエスト）

HermesはMCPのsampling/createMessage機能に対応しています。MCPサーバーはツールの実行中に、エージェントを介してLLMの補完をリクエストできます。これにより、エージェントが処理に参加するワークフロー（データ分析、コンテンツ生成、意思決定）が可能になります。

サンプリングはデフォルトで有効です。サーバーごとに設定してください。

mcp_servers:
  my_server:
    command: "npx"
    args: ["-y", "my-mcp-server"]
    sampling:
      enabled: true           # default: true
      model: "gemini-3-flash" # model override (optional)
      max_tokens_cap: 4096    # max tokens per request
      timeout: 30             # LLM call timeout (seconds)
      max_rpm: 10             # max requests per minute
      allowed_models: []      # model whitelist (empty = all)
      max_tool_rounds: 5      # tool loop limit (0 = disable)
      log_level: "info"       # audit verbosity

サーバーは、複数ターンにわたるツール拡張ワークフロー向けに、サンプリングリクエストにtoolsを含めることもできます。max_tool_rounds設定により、ツールの無限ループを防止できます。サーバーごとの監査メトリクス（リクエスト数、エラー数、トークン数、ツール使用回数）は、get_mcp_status()で追跡されます。

信頼できないサーバーでは、sampling: { enabled: false }を指定してサンプリングを無効にしてください。

注意事項

• エージェントの視点ではMCPツールは同期的に呼び出されますが、専用のバックグラウンドイベントループ上で非同期に実行されます。
• ツールの結果は、{"result": "..."}または{"error": "..."}のいずれかを含むJSONとして返されます。
• ネイティブのMCPクライアントはmcporterとは独立しているため、両方を同時に使用できます。
• サーバー接続は永続的で、同じエージェントプロセス内のすべての会話で共有されます。
• サーバーの追加や削除には、エージェントの再起動が必要です（現在、ホットリロードには対応していません）。