SaaS Tools

11.5. SaaS Tools — The Ready-made OAuth Ecosystem

SaaS Tools — the ready-made OAuth ecosystem. This is the smoothest experience in all of Integrations, thanks to Hermes’s built-in MCP Catalog.

One-click install, no YAML to write

hermes mcp install linear      # from the built-in catalog
hermes mcp add stripe --url https://mcp.stripe.com --auth oauth   # server not in the catalog

The catalog contains entries curated by Nous (located in the optional-mcps/ directory of the official repository — there is no community self-submission tier; every catalog entry goes through PR review). Typical names: Linear, Sentry, Atlassian, Asana, Figma, Stripe, Notion, Vercel, Supabase…

The real installation flow

1. Type hermes mcp install linear → Hermes checks the required authentication type (remote OAuth → automatically opens the browser and handles PKCE).
2. After authentication completes, Hermes probes the server to list all its tools, then shows a tool-selection checklist:

Select tools for 'linear' (SPACE toggle, ENTER confirm)
[x] find_issues       Find issues matching a query
[x] get_issue          Get a single issue
[x] create_issue       Create a new issue
[ ] delete_workspace   Delete a Linear workspace

Only the ticked tools go into mcp_servers.linear.tools.include — meaning you decide at install time, not in a later review. delete_workspace is not ticked by default — a clear example of the “narrow rights by default” principle.

How OAuth 2.1 works under the hood

For servers using the OAuth 2.1 standard (Linear, Sentry, Atlassian, Figma, Stripe…), Hermes handles everything automatically: metadata discovery, client identification (via Client ID Metadata Document — the new mechanism replacing Dynamic Client Registration per the MCP 2026-07-28 spec), token exchange, and refresh on expiry. Tokens are stored at ~/.hermes/mcp-tokens/<server>.json with restricted file permissions (0o600) and are silently reused until a refresh fails, at which point you log in again.

When Hermes runs on a remote server (not the same machine as your browser), there are 2 ways to complete OAuth: manually paste the redirect URL into the prompt, or SSH port-forward a local listener to the machine that has a browser.

Field-tested lessons

• When installing a new SaaS server, always stop at the tool checklist step — do not tick “select all for speed”. Unticking delete_* and revoke_* from the start is much cheaper than cleaning up the consequences later.
• Some providers (such as Stripe, according to community reports) tend to revoke OAuth sessions periodically — if you hit repeated “not connected” errors, consider switching to a restricted API key instead of OAuth for higher stability on long-running background workloads.
• For static API keys (not OAuth), Hermes stores them in ~/.hermes/.env — remember to back up/restore this exact file when moving environments, not just config.yaml.