MCP 設定の早見表

このページは、MCP の本編ドキュメントに対応する簡潔な早見表です。

考え方から知りたいときは、こちらをご覧ください。

• MCP (Model Context Protocol)
• Hermes で MCP を使う

設定全体のかたち

mcp_servers:
  <server_name>:
    command: "..."      # stdio servers
    args: []
    env: {}

    # OR
    url: "..."          # HTTP servers
    headers: {}

    # Optional HTTP/SSE TLS settings:
    ssl_verify: true                # bool or path to a CA bundle (PEM)
    client_cert: "/path/to/cert.pem"  # mTLS client certificate (see below)
    # client_key: "/path/to/key.pem"  # optional, when key lives in a separate file

    enabled: true
    timeout: 120
    connect_timeout: 60
    supports_parallel_tool_calls: false
    tools:
      include: []
      exclude: []
      resources: true
      prompts: true

サーバーごとのキー

環境変数の参照

サーバーの設定に出てくる文字列は、どこであっても（env、headers、args、url など）${VAR} または Cursor 風の SecretRef 形式 ${env:VAR} で環境変数を参照できます。どちらも同じ変数に解決されるので、Cursor や Claude の設定からコピーしてきた MCP の断片がそのまま動きます。

mcp_servers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${env:GITHUB_TOKEN}"   # same as "${GITHUB_TOKEN}"

値は、いま使っているプロファイルの秘密情報の範囲から解決されます（見つからなければプロセスの環境変数を見ます）。ですので、秘密の値は ~/.hermes/.env に置いてください。設定されていない変数は、書いたままの文字列として残ります。ただし、リモートのサーバーの url や headers では例外です。そこで ${VAR} をそのまま送ると必ず 401 になり、資格情報が間違っているように見えてしまうため、接続は安全側に倒して失敗させ、サーバーの状態にその変数名を出します（MCP server 'name': ${VAR} in url/headers is not set in this profile's .env or secret source）。プロファイルの .env（またはその秘密情報の取得元）を直してください。次に接続を試みるとき、参照はあらためて展開されます。

コンテキスト変数

環境変数だけでなく、Cursor 風のコンテキスト変数も差し込まれます（名前は大文字と小文字を区別します）。

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    env:
      CACHE_DIR: "${userHome}${/}.cache${/}mcp"

これ以外の ${...} は、上で説明した環境変数の探索に回されます。

tools の方針キー

絞り込みの動き

include

include を書くと、サーバーが元から持つ MCP ツールのうち、そこに挙げたものだけが登録されます。

tools:
  include: [create_issue, list_issues]

exclude

exclude だけを書いて include を書かないと、そこに挙げた名前を除く、サーバーが元から持つ MCP ツールがすべて登録されます。

tools:
  exclude: [delete_customer]

どちらが優先されるか

両方を書いた場合は include が勝ちます。

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

結果はこうなります。

• create_issue はそのまま使えます
• delete_issue は、include が優先されるので無視されます

ユーティリティツールの方針

Hermes は、MCP サーバーごとに次のユーティリティの包みを登録することがあります。

リソース関連:

• list_resources
• read_resource

プロンプト関連:

• list_prompts
• get_prompt

リソースを使わない

tools:
  resources: false

プロンプトを使わない

tools:
  prompts: false

能力に応じた登録

resources: true や prompts: true にしていても、Hermes がそのユーティリティツールを登録するのは、MCP のセッションが対応する能力を実際に備えているときだけです。

ですから、次のようなことは正常な動きです。

• プロンプトを使う設定にした
• でもプロンプト関連のツールが出てこない
• サーバーがプロンプトに対応していないから

enabled: false

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

このときの動きです。

• 接続を試みません
• ツールの探索もしません
• ツールの登録もしません
• 設定はそのまま残るので、あとでまた使えます

結果が空になったとき

絞り込みでサーバー本来のツールが一つも残らず、ユーティリティツールも登録されない場合、Hermes はそのサーバーのために空の MCP ツール群を作ることはしません。

設定の例

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]
      resources: false
      prompts: false

Stripe で一部を外す

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:
      include: []
      resources: true
      prompts: false

TLS のクライアント証明書（mTLS）

クライアント証明書を求めてくる HTTP/SSE のサーバーには、client_cert を（必要なら client_key も）指定します。

mcp_servers:
  # Combined cert + key in a single PEM file
  internal_api:
    url: "https://mcp.internal.example.com/mcp"
    client_cert: "~/secrets/mcp-client.pem"

  # Separate cert and key files
  partner_api:
    url: "https://mcp.partner.example.com/mcp"
    client_cert: "~/secrets/client.crt"
    client_key: "~/secrets/client.key"

  # Encrypted key with a passphrase (3-element list form)
  bank_api:
    url: "https://mcp.bank.example.com/mcp"
    client_cert: ["~/secrets/client.crt", "~/secrets/client.key", "my-passphrase"]

  # Custom CA bundle (private CA / self-signed server)
  lab_api:
    url: "https://mcp.lab.local/mcp"
    ssl_verify: "~/secrets/lab-ca.pem"
    client_cert: "~/secrets/lab-client.pem"

補足です。

• パスの ~ は展開されます。ファイルが見つからないときは、接続しようとした時点で、そのサーバーの名前を添えたエラーですぐ止まります。
• ssl_verify: false にすると、サーバー証明書の検証をまったくしなくなります。本番のサービスに対しては使わないでください。
• Streamable HTTP と SSE のどちらでも使えます。

設定を読み直す

MCP の設定を変えたあとは、次のコマンドでサーバーを読み直します。

/reload-mcp

ツールの名前の付き方

サーバーが元から持つ MCP ツールは、次の名前になります。

mcp__<server>__<tool>

例です。

• mcp__github__create_issue
• mcp__filesystem__read_file
• mcp__my_api__query_data

ユーティリティツールにも、同じ形で接頭辞が付きます。

• mcp__<server>__list_resources
• mcp__<server>__read_resource
• mcp__<server>__list_prompts
• mcp__<server>__get_prompt

アンダースコア 2 つの区切り（mcp__…__…）は Claude Code、Codex、OpenCode と同じ書き方で、サーバー名やツール名にアンダースコアが含まれていても、どこが境目なのかが分かるようにしています。

名前の整え方

サーバー名とツール名のどちらでも、英数字とアンダースコア以外の文字（ハイフン、ドット、空白など）は、登録の前にアンダースコアへ置き換えられます。こうしておくと、LLM の関数呼び出し API で使える名前になります。

たとえば my-api という名前のサーバーが list-items.v2 というツールを公開している場合は、こうなります。

mcp__my_api__list_items_v2

include や exclude を書くときは、この点にご注意ください。置き換えたあとの名前ではなく、元の MCP ツール名（ハイフンやドットの付いたもの）を書きます。

OAuth 2.1 の認証

OAuth を必要とする HTTP サーバーには、そのサーバーの設定に auth: oauth を書きます。

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth

このときの動きです。

• Hermes は MCP SDK の OAuth 2.1 PKCE の流れ（メタデータの探索、クライアントの識別、トークンの取得、更新）を使います
• 最初に接続するとき、承認のためにブラウザーの画面が開きます
• トークンは ~/.hermes/mcp-tokens/<server>.json（名前付きのプロファイルでは ~/.hermes/profiles/<name>/mcp-tokens/）に保存され、次のセッションでも使い回されます
• トークンの更新は自動です。更新に失敗したときだけ、もう一度承認を求めます
• HTTP/StreamableHTTP でつなぐサーバー（url を書いたもの）だけが対象です
• 多重化したゲートウェイ のもとでは、OAuth の接続がプロファイルをまたいで共有されることはありません。mcp_servers の設定がまったく同じでも、プロファイルごとに自分のトークンで認証し、自分の接続を開きます

デバイスコードでのログイン（RFC 8628）

device_authorization_endpoint を知らせている認可サーバーに対しては、Hermes を動かしている 端末のターミナルから、デバイス認可をはっきり選んで実行します。

hermes mcp login protected_api --flow device

表示された確認用の URL をどの端末でもよいので開き、画面に出たユーザーコードを入れてください。 Hermes は承認されるまで問い合わせを続け、authorization_pending と slow_down に従い、 断られたときや期限が切れたときは止まります。ブラウザーは開かず、折り返しを受ける待ち受けも要りません。 承認を待つ時間の上限は oauth.timeout で決まり（既定は 300 秒）、コード自体の有効期限でも制限されます。 サーバーの保護リソースのメタデータに認可サーバーが複数並んでいる場合、デバイスでのログインはそれを順に調べ、 メタデータの発行者（issuer）が公開している URL と一致し、かつ device_code による許可に対応している最初のサーバーを使います（ブラウザ専用のサーバーが先頭にあっても飛ばします）。 唯一認められる違いは、MCP の機能ガイドの「OAuth で認証する HTTP サーバー」で説明している、 パスを含む形だけです（https://host/path として公開されているサーバーの /.well-known/oauth-authorization-server/path にある文書が https://host を名乗る場合）。

サーバーに oauth.flow: device を書いておくと、hermes mcp login と hermes mcp reauth （reauth --all を含みます）がデバイス認可を使うようになります。login --flow browser は、その 設定を 1 回のログインだけ上書きします。既定は引き続きブラウザーの PKCE です。対応していない メタデータのときは、黙って別の流れに切り替わるのではなく、手掛かりのあるエラーが出ます。

デバイスでのログインは、動的なクライアント登録の際にデバイス許可と更新用の許可を求めるか、 設定してある oauth.client_id、oauth.client_secret、oauth.token_endpoint_auth_method を使います。 登録したクライアントがデバイス認可を許している必要があります。ブラウザー向けの CIMD 文書は使いません。 oauth.scope はデバイス認可の要求に付いて送られ、oauth.user_agent はトークンの問い合わせにも効きます。 トークン、登録内容、発行元のメタデータは、動いているプロファイルの MCP トークン置き場に残り、 これまでどおりの更新の仕組みが再起動後もそれらを使い回します。 失敗したデバイス許可が、すでに保存してある認証情報を置き換えることはありません。

最初のデバイスログインはターミナルからだけです。ダッシュボードやブラウザーからの折り返し、 裏側での再接続では、デバイス認可は始まりません。ログインのコマンドは、ゲートウェイと 同じプロファイル・同じホスト に対して実行してください。使える更新用トークンがないまま デバイス許可の期限が切れたり断られたりした場合は、もう一度はっきりログインし直す必要があります。

クライアントの識別: CIMD と DCR

Hermes は自分が何者かを認可サーバーに伝えるのに、Client ID Metadata Document（CIMD）を使います。これは MCP の 2026-07-28 版の仕様が、動的クライアント登録（DCR）に代えて採り入れた仕組みです。この文書は https://nousresearch.github.io/hermes-agent/docs/oauth/client-metadata.json に置かれていて、この URL 自体が client_id になります。認可サーバーはこれを取得して、Hermes の名前、ロゴ、許可されたリダイレクト先を知ります。インストールごとに何かを登録することはありませんし、利用者ごとの情報も含みません。

最後に決めるのは認可サーバーです。SDK がこの文書の URL を client_id として送るのは、サーバーがメタデータで client_id_metadata_document_supported: true を掲げているときだけで、そうでなければ従来どおり DCR で登録します。DCR は MCP の仕様では非推奨になりましたが、いま動いているサーバーのほとんどは今も DCR を使っています。

コールバックのポート

この文書には、ループバックのリダイレクト先が決まった組み合わせで書かれています。仕様では、認可のリクエストに載せるリダイレクト先がそのどれかと*文字列として完全に一致*していなければならないので、CIMD の流れでは Hermes がふだん選ぶ、その場限りの大きい番号のポートは使えません。そこで Hermes は、コールバックを 27890〜27894 のどれかに固定します。

この固定は、サーバーが何に対応しているか分かる前に決めなければなりません。リダイレクト先は流れの最初に決まるのに、サーバーのメタデータが届くのは途中だからです。ですので Hermes は、CIMD を使う*可能性のある*流れではポートを固定し、それ以外ではその場限りのポートに戻します。

• 一度つないだことがあり、保存されたメタデータに CIMD が書かれていないサーバーは、これまでどおりその場限りのポートを使います。
• Hermes が一度もつないだことのないサーバーは、その初回ログインで固定のポートを使います。当てにいくしか CIMD を使う道がないからです。
• コールバックの場所が変わる要素があると、その場限りのポートに戻ります。あらかじめ登録した oauth.client_id、oauth.client_secret、独自の oauth.client_name や oauth.token_endpoint_auth_method、oauth.redirect_uri や oauth.redirect_port の上書き、ダッシュボードやデスクトップからのログイン、ディスクに残っているクライアント登録、そして 5 つのポートすべてが他のプロセスに使われている場合です。

固定したポートは、決まった時点ですぐ確保され、ブラウザーからのリダイレクトが届くまで押さえたままになります。ですので、同時に 2 つのログイン（別のプロファイルや、同じプロセス内の別のサーバー）が走っても、同じ待ち受け口に重なることはありません。

サーバーが文書を受け付けないとき

サーバーが文書を取得したうえで、*トークン*のエンドポイントで断ってきた場合（invalid_client）、Hermes はその拒否を記録に残し、~/.hermes/mcp-tokens/<server>.cimd-off に書き留めて、そのサーバーには以後 DCR を使います。

文書をそもそも取得できない、あるいは検証できないサーバーの場合は、リダイレクトが起きる前に*認可*のエンドポイントで止まります。そこには Hermes が観測できる手がかりがないので、ブラウザーには invalid-client のエラーが出て、ログインは 5 分で時間切れになります。時間切れのメッセージはその文書の名前を挙げ、cimd: false を指し示します。hermes mcp login <server> を実行すると記録した拒否が消えるので、文書を直せばもう一度試せます。

サーバーごとに書ける任意のキー

mcp_servers:
  protected_api:
    url: "https://mcp.example.com/mcp"
    auth: oauth
    oauth:
      client_metadata_url: "https://example.com/my-cimd.json"  # self-hosted document
      cimd: false                                              # force DCR
      user_agent: "My-MCP-Client/1.0"                          # token-request User-Agent

client_metadata_url は、パスの付いた HTTPS の URL でなければなりません（オリジンだけ、フラグメント付き、ユーザー情報付き、. や .. を含むものは使えません）。そのうえで リダイレクトなしで 200 と Content-Type: application/json を返す必要があります。認可サーバーは、この文書を取りにいくときにリダイレクトをたどることを禁じられているからです。Hermes はこの場合もコールバックを同じ 27890〜27894 の範囲に固定するので、自分で用意する文書には 10 個のループバック URL（各ポートについて http://127.0.0.1:<port>/callback と http://localhost:<port>/callback）をすべて書き、client_id にはその文書自身の URL を書いてください。

user_agent は、既定の User-Agent を トークンのエンドポイントへのリクエストに限って（認可コードの引き換え、更新、デバイスフローでのトークンの問い合わせ）差し替えます。これを書かない場合、Hermes は Hermes-Agent/<version> を送ります。ヘッダーなしで送ることはありません。WAF の内側にある認可サーバーは、ヘッダーなしのリクエストに 403 を返すからです。MCP の通信には使われませんし、トークンのリクエストで設定できるヘッダーは他にありません。空の値や null は無視されます。引き換えに失敗したときは、ステータスと、エラー本文を短く伏せ字にした抜粋を一緒に知らせます（WAF の「Request blocked」ページなのか、発行者の invalid_grant なのかが分かります）。パケットを取らなくても原因が見えるようにするためです。hermes mcp login は、古くなった許可とクライアント登録を消してから認可をやり直しますが、認可サーバーのメタデータのキャッシュは残します。そのため、メタデータの文書を取り直せないときでも、案内される認可の URL は最初に見つけたものが使われます。

OAuth の探索とクライアントの動的な登録のリクエスト（/.well-known/... のメタデータ文書と registration_endpoint への POST）には、つねに User-Agent: Hermes-Agent/<version> が付きます。MCP の SDK はこれらのリクエストをクライアント既定のヘッダーなしで組み立てるため、WAF の後ろにいる認可サーバーはヘッダーのないリクエストに 403 を返します。するとメタデータ文書が読めないように見え、登録は MCP のホスト上の /register を当て推量で叩く方へ落ち、最後は Registration failed: 404 でログインに失敗します。メタデータの取得がすべて失敗した場合、エラーはまず今回のステータスを先に示すようになりました（Could not read authorization-server metadata (403 from https://…/.well-known/oauth-authorization-server; …)）。登録の代替処理そのもののエラーはその後ろに続きます。

Add to Hermes のリンク

MCP を提供する側やそのドキュメントでは、Hermes のデスクトップアプリを開いてサーバーの設定をあらかじめ入れておく、ワンクリックの 「Add to Hermes」 ボタンを置けます。Cursor の cursor://anysphere.cursor-deeplink/mcp/install と同じ考え方です。

hermes://mcp/install?name=NAME&config=BASE64

• name — サーバーの名前です。^[A-Za-z0-9._-]{1,64}$ に合っている必要があります。
• config — サーバー設定のオブジェクトを base64url で符号化した JSON です（普通の base64 も受け付けます）。復号した JSON はオブジェクトで、文字列の url（http:// か https:// のみ）か文字列の command のどちらかを持っている必要があり、上で説明したサーバーのキーはどれでも書けます。32KB を超えるものは受け付けません。

例です（JavaScript）。

const config = { url: 'https://mcp.example.com/mcp' }
const link = `hermes://mcp/install?name=example&config=${btoa(JSON.stringify(config))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')}`

リンクを開いただけで何かが入ることはありません。デスクトップアプリは、サーバーの名前と、整形した設定の全文を確認の画面に出し（command を使うサーバーは手元でプロセスを動かすので、追加の注意も添えます）、利用者がはっきり承認しないと進みません。すでにある名前が上書きされることもなく、名前を変えるか取りやめるかを尋ねます。