Configure MCP Transport, TLS, and OAuth Safely

Hermes can connect to local MCP servers over stdio or remote servers over HTTP. Transport choice changes the security boundary: stdio launches a local subprocess with an explicit environment, while HTTP depends on URL, TLS verification, headers or OAuth, network policy, and the remote service’s identity.

Choose one transport clearly

A stdio entry uses command, args, and a limited env mapping. An HTTP entry uses url and optional headers. Do not mix them casually or place reusable bearer tokens directly in a public repository. For remote endpoints, leave ssl_verify: true unless a test environment has a documented reason and isolation boundary.

Private PKI can use a custom CA bundle. Mutual TLS can use a combined certificate-and-key PEM, separate certificate and key files, or the supported encrypted-key form. Paths are expanded by Hermes and missing files fail at connection time with a server-scoped error.

Connection checklist

Select stdio or HTTP based on the server’s supported transport.
Keep subprocess environment variables to the minimum required.
Require HTTPS for remote production servers.
Keep server certificate verification enabled.
Use a custom CA bundle rather than disabling verification for private PKI.
Protect client certificate and key files with host filesystem permissions.
Use auth: oauth for supported OAuth 2.1 HTTP servers.
Set conservative connect and tool-call timeouts.
Reload MCP configuration and inspect only server-scoped status.
Test with a read-only tool before enabling mutations.

OAuth boundary

For HTTP MCP servers configured with OAuth, Hermes uses the MCP SDK’s OAuth 2.1 flow with PKCE, metadata discovery, client registration when supported, token exchange, persistence, and refresh. Tokens are stored in the Hermes MCP token directory by server name. Protect that directory as credential-bearing state, and reauthorize when refresh fails rather than copying tokens between machines.

Preflight and compatibility

Hermes normally probes HTTP endpoints to fail fast when a URL does not look like a valid MCP transport. skip_preflight exists for legitimate Streamable HTTP endpoints whose probe response is nonstandard; it should not become a blanket cure for incorrect URLs, TLS failures, or authentication problems.

Common pitfalls

Setting ssl_verify: false to bypass an untrusted or mismatched certificate in production.
Committing bearer headers, certificate keys, or OAuth token files.
Using a client certificate without verifying the remote server certificate.
Disabling preflight before inspecting the endpoint and content type.
Confusing connection timeout with tool execution timeout.
Reusing one OAuth token file name across distinct server identities.
Enabling mutation tools before transport and identity checks pass.

Verification steps

Reload MCP configuration and confirm the intended server connects over the selected transport.
For HTTP, inspect the negotiated certificate chain and expected hostname without exposing credentials.
For mTLS, prove the server rejects a client without the certificate and accepts the intended client.
For OAuth, complete PKCE, restart Hermes, and confirm refresh/persistence works.
Call a read-only tool and verify timeout and error behavior.
Remove or invalidate the credential in a test environment and confirm the connection fails closed.
Scan config and repository history for embedded headers, keys, and token files.

Official documentation

https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference