# How to add an MCP server to Hermes Agent > Add a local or remote MCP server to Hermes Agent: the mcp_servers config, OAuth with hermes mcp login, tool filters, and fixes for the common errors. Updated 2026-10-17 · https://upsy.ai/guides/hermes/add-mcp-server ## 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 `, and check it with `hermes mcp test `. 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](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)): - **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](/guides/hermes) 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](https://upsy.ai). There's no API key. ## Add a remote server with OAuth (Upsy) 1. Sign up at [upsy.ai](https://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: ```yaml 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](https://github.com/NousResearch/hermes-agent/issues/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`: ```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____` ([config reference](https://hermes-agent.nousresearch.com/docs/reference/mcp-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: ```yaml 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](https://hermes-agent.nousresearch.com/docs/user-guide/security)); 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 | Key | What it does | |---|---| | `url` | An HTTP server's endpoint | | `auth: oauth` | Browser sign-in with OAuth 2.1 and PKCE | | `headers` | Fixed headers, such as `Authorization: "Bearer ${MY_TOKEN}"` | | `command`, `args`, `env` | What a stdio server runs, and its environment | | `timeout` | Seconds per tool call (default 300) | | `connect_timeout` | Seconds to connect (default 60; `hermes mcp add` and `test` use 30 when unset) | | `oauth.timeout` | How long `hermes mcp login` waits for you (default 300) | | `enabled`, `tools`, `trust` | Turning a server off, and the filters above | ## 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 :127.0.0.1: 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](https://github.com/NousResearch/hermes-agent/issues/137326) 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](https://github.com/NousResearch/hermes-agent/issues/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. --- Upsy connects personal AI assistants (Muse, Grok, ChatGPT, Claude, Cursor, Claude Code, Codex, Devin) to your Gmail, Google Calendar, Google Drive, Slack, Notion and other apps through one MCP server, with a shared memory, files and a cloud browser signed in to your sites. You choose what each assistant may do in each app, see everything it did, and turn it off in one click. Upsy is free. To add Upsy to an assistant, add a remote MCP server (Streamable HTTP) named Upsy at https://upsy.ai/connect. It signs in with OAuth; there is no API key.