From 630a4eb3a1000aac8ee8a37c4cc5b8c06d4fbe6d Mon Sep 17 00:00:00 2001 From: teknium1 <127238744+teknium1@users.noreply.github.com> Date: Sun, 13 Sep 2026 12:22:15 -0700 Subject: [PATCH] docs(mcp): mTLS credentials count toward connection sharing; OAuth token path is per profile The multiplex guide now says client_cert/client_key are part of the "same credentials" test and states the OAuth rule as its own sentence; the MCP config reference names the per-profile token directory and the never-shared-across-profiles rule next to the OAuth behaviour list. Co-authored-by: ly6751 <99090550+ly6751@users.noreply.github.com> --- website/docs/reference/mcp-config-reference.md | 3 ++- website/docs/user-guide/multi-profile-gateways.md | 8 +++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/website/docs/reference/mcp-config-reference.md b/website/docs/reference/mcp-config-reference.md index f1e4fbdba8..103fcbc2f5 100644 --- a/website/docs/reference/mcp-config-reference.md +++ b/website/docs/reference/mcp-config-reference.md @@ -333,9 +333,10 @@ mcp_servers: Behavior: - Hermes uses the MCP SDK's OAuth 2.1 PKCE flow (metadata discovery, client identification, token exchange, and refresh) - On first connect, a browser window opens for authorization -- Tokens are persisted to `~/.hermes/mcp-tokens/.json` and reused across sessions +- Tokens are persisted to `~/.hermes/mcp-tokens/.json` (a named profile uses `~/.hermes/profiles//mcp-tokens/`) and reused across sessions - Token refresh is automatic; re-authorization only happens when refresh fails - Only applies to HTTP/StreamableHTTP transport (`url`-based servers) +- Under a [multiplexed gateway](/user-guide/multi-profile-gateways), an OAuth connection is never shared across profiles: each profile authenticates with its own token and opens its own connection, even when the `mcp_servers` entries are identical ### Device-code login (RFC 8628) diff --git a/website/docs/user-guide/multi-profile-gateways.md b/website/docs/user-guide/multi-profile-gateways.md index 1a0d10084e..3b81c9d701 100644 --- a/website/docs/user-guide/multi-profile-gateways.md +++ b/website/docs/user-guide/multi-profile-gateways.md @@ -327,9 +327,11 @@ profile B receives B's value for such a name, or nothing if B has none, never th default profile's. MCP servers are connected **per profile**: two profiles that both name a server `github` with their own token get two connections and each sees only its own tools; profiles whose `mcp_servers` entry is identical (same -route *and* credentials) share one connection — except `auth: oauth` servers, which are -never shared: each profile holds its own token and opens its own connection — and an owner's `/reload-mcp` -re-registers the sharing profiles' tools without them reloading. Terminal settings +route *and* credentials, including mTLS `client_cert`/`client_key`) share one +connection, and an owner's `/reload-mcp` +re-registers the sharing profiles' tools without them reloading. `auth: oauth` +servers are never shared across profiles: each profile holds its own token under +its own `mcp-tokens/` and opens its own connection. Terminal settings (`terminal.backend`, `terminal.cwd`, `terminal.docker_volumes`, `terminal.docker_shared_container_key`, SSH targets, …) are likewise resolved per profile on every routed turn: a profile that omits a terminal key gets the