How to add an MCP server to Hermes Agent

Short answer

Hermes Agent reads MCP servers from mcp_servers in ~/.hermes/config.yaml. For a remote server that signs in with OAuth, save it with hermes config set, sign in with hermes mcp login <name>, and check it with hermes mcp test <name>. It takes about two minutes. MCP ships with the standard install, and Hermes is open source, so there's no plan to buy. The steps use Upsy as the example, checked against Hermes v0.22.2, the current release.

Two kinds of MCP servers

An MCP server is a small program that offers Hermes tools, like "search email" or "create issue". Hermes takes two kinds (Hermes's MCP docs):

• Stdio servers run on your machine as a child process: a command, its args and any env. Most npx and uvx servers work this way.
• HTTP servers run somewhere else: a url, plus headers for a fixed token or auth: oauth for a browser sign-in. Hermes speaks Streamable HTTP, and transport: sse covers older SSE-only servers.

Check Hermes's catalog first. hermes mcp opens a picker of 65 servers Nous Research reviewed, like Linear, Notion, Atlassian and Stripe, and hermes mcp install linear installs one. If yours is there, that's the easy way. The Hermes connectors hub covers what else Hermes connects to.

What you need

• Hermes Agent with a model set up.
• For an HTTP server, its exact URL. Hermes connects from its own machine, so an address on your network or VPN works too.
• For OAuth, a browser. If Hermes runs on a server, see Troubleshooting.
• For a stdio server, its runtime, usually Node.js or uv.
• For Upsy, a free account at upsy.ai. There's no API key.

Add a remote server with OAuth (Upsy)

1. Sign up at upsy.ai with Set up Upsy, and connect the apps you want under Apps.

2. Optional: on Upsy's Assistants page, click Add assistant and pick Hermes under Which assistant?. Upsy shows these steps with the commands to copy.

3. Save the server. Nothing connects yet:

   hermes config set mcp_servers.upsy.url https://upsy.ai/connect
   hermes config set mcp_servers.upsy.auth oauth
   

4. Sign in:

   hermes mcp login upsy
   

   Hermes prints an authorization URL and opens your browser when it can. On the Upsy page, sign in. Everything starts ticked: untick what Hermes shouldn't use, choose full access or Read-only for each app, and click Allow. Hermes waits up to five minutes, then prints Authenticated — N tool(s) available.

5. Start a new hermes chat, or run /reload-mcp in one that was already open.

Your config now has:

mcp_servers:
  upsy:
    url: https://upsy.ai/connect
    auth: oauth

Hermes refreshes the tokens itself and signs in as "Hermes Agent", the name Upsy's Assistants page shows. Any other OAuth server works the same way with its own name and URL. If a Hermes chat is open during step 3, it may try to connect on its own within 30 seconds; ignore that and use hermes mcp login.

hermes mcp add or hermes config set?

hermes mcp add saves a server in one command, which suits stdio servers and fixed tokens. With OAuth it connects before it saves, and the whole browser sign-in must fit in the connection timeout, 30 seconds unless you set one. Still on the consent page? It fails with Connecting to MCP server 'upsy' timed out after 30s, then asks "Save config anyway (you can test later)?" and saves the server turned off if you say yes (issue #49759).

hermes mcp login waits for oauth.timeout, 300 seconds by default, plus 15. Hence: save first, sign in second. For one command, give it more time:

hermes mcp add upsy --url https://upsy.ai/connect --auth oauth --connect-timeout 300

The timeout is saved in the server's config too. Once connected, hermes mcp add lists the tools and asks Enable all N tools? [Y/n/select]. Choosing select saves only the tools you tick.

Add a local (stdio) server

For a server that runs on your machine, hermes mcp add is the quick way:

hermes mcp add filesystem --command npx --args -y @modelcontextprotocol/server-filesystem /home/you/projects

Put --args last: everything after it goes to the command. Secrets go in --env KEY=VALUE. In config.yaml:

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

A stdio server gets only the env you set plus a safe baseline, not your whole shell environment, and ${GITHUB_TOKEN} is read from ~/.hermes/.env. Coming from Claude Code? hermes import-agent claude-code copies its mcpServers into Hermes's config.

Check that it works

hermes mcp test upsy

It connects, prints Connected and lists the tools it found. It exits with 0 on success, 1 when the connection fails and 3 when no server has that name. hermes mcp list shows every server and whether it's enabled.

Then ask Hermes:

Using Upsy, list my connected apps and what you're allowed to do with each.

Hermes names MCP tools mcp__<server>__<tool> (config reference), so this calls mcp__upsy__upsy_connectors, often through tool_search and tool_call, since Hermes loads MCP tools on demand. It should list each app and account with Hermes's access. In Upsy, the call shows in History under Hermes Agent.

Choose which tools Hermes sees

Each server takes a tools filter:

mcp_servers:
  upsy:
    url: https://upsy.ai/connect
    auth: oauth
    tools:
      exclude: [send_message, email_trash]

• include keeps only the listed tools; exclude drops them; include wins if both are set. Both take globs like email_*, and the server's own tool names, not the mcp__ ones.
• hermes mcp configure upsy opens a checklist and writes include for you.
• enabled: false keeps the entry but skips it.
• trust: untrusted makes Hermes ask before every tool not marked read-only. Otherwise it never asks.

Upsy adds limits on its side: Full access, Read-only, Pick actions or No access per app, on Hermes's page under Assistants. Hermes's filters live in config.yaml, which Hermes's own file tools can still write (security docs); Upsy's server refuses any tool Hermes isn't allowed. Use both if you like, and run /reload-mcp after a change.

Config keys you'll use

Troubleshooting

Connecting to MCP server 'upsy' timed out after 30s

You used hermes mcp add and the sign-in took longer than 30 seconds. If you saved it anyway, the server is off. Turn it on and sign in:

hermes config set mcp_servers.upsy.enabled true
hermes mcp login upsy

hermes mcp add asks "Does this server require authentication?"

You left out --auth oauth, so Hermes wants an API key, which Upsy doesn't have. Press Ctrl-C and add --auth oauth, or use the hermes config set steps. If hermes mcp login says Server 'upsy' is not configured for OAuth, set mcp_servers.upsy.auth to oauth and log in again.

Hermes runs on a server, and the sign-in can't finish

The sign-in ends on a local port of the machine running Hermes, which your laptop's browser can't reach. Either:

• Paste it back. Hermes also prints "Or paste the redirect URL here". Approve in your browser, copy the full URL it lands on (a connection error there is expected) and paste it.
• Forward the port with ssh -N -L <port>:127.0.0.1:<port> you@host, using the port in the authorization URL. Hermes prints this hint over SSH.

Device-code sign-in (--flow device) needs server support, and Upsy doesn't offer it.

non-interactive environment and no cached tokens found

The messaging gateway tried to connect before you signed in, and it never opens a browser. Run hermes mcp login upsy in a terminal on the same machine and profile. The gateway retries on its own and picks up the token.

The server rejected the sign-in. Run: hermes mcp login upsy

The token was refused and couldn't be refreshed, for example after you clicked Remove on Hermes's page in Upsy. Do what it says. hermes mcp reauth --all signs in to every OAuth server in turn.

Tools don't show up in a chat

A session keeps the tool list it started with. Run /reload-mcp or start a new chat. If /reload-mcp fails with is bound to a different event loop, start a new session: it's an open bug with OAuth servers.

The user hasn't allowed you to use …

Upsy refused a tool at Hermes's access level. Raise it on Hermes's page in Upsy, or connect the app under Apps if the message says it isn't connected.

SSE stream ended without a response

In v0.22.2, a server whose tool list comes as one event over 1 MiB can't connect, and this misleading message is all you get (issue #138329). Servers with thousands of tools, like Cloudflare's full API, hit it. Your sign-in is fine.

Security and privacy

• Tokens stay local in ~/.hermes/mcp-tokens/, readable only by you. Hermes's file tools can't write there.
• Hermes cleans tool results, stripping invisible Unicode tag characters, a known way to hide instructions.
• No prompt by default. Hermes runs MCP tools without asking, and Upsy has no approval step of its own. For a yes or no before each send, add trust: untrusted to Upsy's entry. Upsy marks its read tools read-only, so Hermes then asks only before the rest, like sending, deleting or clicking in the browser.
• Upsy holds the app tokens. Hermes calls Upsy, and Upsy calls the app. Every call is in History, and Upsy emails you when one assistant sends 20+ messages, deletes 50+ items or reads from your apps 100+ times within 10 minutes.
• Turning it off: hermes mcp remove upsy deletes the entry and its tokens. Remove on Hermes's page in Upsy cuts access at once.

FAQ

Does Hermes Agent support MCP?

Yes, in the standard install: local stdio servers and remote HTTP servers, with OAuth.

Where is Hermes's MCP config?

Under mcp_servers in ~/.hermes/config.yaml. hermes config path prints the exact file; each named profile has its own.

Do I need to restart Hermes after adding a server?

No. Run /reload-mcp or start a new chat. A running messaging gateway notices config changes within about a minute.

Can I use MCP servers from Telegram or Discord?

Yes. The messaging gateway loads the same servers. Sign in to OAuth servers from a terminal first.

Does Upsy need an API key in Hermes?

No. It signs in with OAuth, and Hermes refreshes the tokens itself.