Hermes agent + Notion: how the MCP integration actually works

Short answer: a Hermes agent connects to Notion through an MCP (Model Context Protocol) server. You register the MCP endpoint with the agent — either Notion's own connector or a small server in front of the Notion API — and the agent can then read databases, create pages, and update rows as tool calls. The agent stays on its VPS; Notion access is scoped by an integration token you control.

We run this in production: a Hermes agent on a VPS that reads leads and project data through an MCP endpoint, then writes plans and updates back. Here is the setup that has held up, and the traps that cost us time.

The architecture that works

Three pieces, each replaceable:

• The agent — Hermes running as a long-lived process on a VPS (systemd keeps it alive), talking to you through a gateway like Telegram or a web UI.
• The MCP server — the bridge that exposes Notion (or your app's data) as typed tools: list_leads, get_page, create_row. This can be Notion's hosted MCP, an open-source Notion MCP server, or ~200 lines in your own app.
• The Notion integration token — created at notion.so/my-integrations and granted access to ONLY the databases the agent should touch. This is your blast-radius control.

The agent never holds raw database credentials. It holds one bearer token for the MCP endpoint, and the MCP server holds the Notion token. Revoke either and the agent is locked out.

Registering the MCP with Hermes

Hermes takes remote MCP servers with a URL and an auth header. The shape is:

hermes mcp add notionalize \
  --url https://yoursite.com/api/mcp \
  --auth "Authorization: Bearer <MCP_TOKEN>"

After a gateway restart, the agent lists the server's tools and can call them mid-conversation. From the operator's side it looks like this: you message the bot "what came in this week?", the agent calls list_leads, reads the rows, and answers with the summary — no copy-pasting from Notion.

What to build first

Do not start with "the agent manages our whole workspace." Start with one read-mostly loop:

1. Read + summarize. The agent reads a database (leads, tasks, content calendar) and reports. Zero write risk, immediate daily value.
2. Read + draft. The agent drafts something from the data — a client plan, a weekly digest — and posts it for a human to review.
3. Scoped writes. Only after the first two are boringly reliable: let it update a status property or append a row, never delete.

That ordering is the difference between an agent your team trusts and one that gets unplugged in week two.

The traps that actually bite

• Integration access, not code, is the usual failure. A Notion query that returns 0 rows almost always means the integration was never added to that database's connections — not an empty table. Check ••• → Connections first.
• Column renames break hardcoded property reads. Someone renames "Status" to "Stage" and the agent silently stops seeing updates. Read properties by type where you can, and log loudly when an expected property is missing.
• Gateway restarts eat sessions. On a VPS, wire the agent under systemd with a watchdog — a reload that half-kills the gateway looks exactly like "the bot ignored me."
• Scope creep in the token. One integration token per agent, per purpose. The convenience of a workspace-wide token is precisely its risk.

Is this worth it versus plain automation?

If the job is deterministic — form comes in, row gets created, ping goes out — use a workflow tool (Relay.app, Make, n8n) and skip the agent entirely. An agent earns its keep when the step needs judgment: summarizing messy rows, drafting a plan from context, deciding what deserves attention. Most real systems we build use both: automations move the data, the agent reads it and thinks.

FAQ

Does Notion have an official MCP server? Yes — Notion ships a hosted MCP connector, and there are solid open-source Notion MCP servers. For app-specific data (your own leads table, enriched fields), a small custom MCP in your app usually beats forcing everything through raw Notion tools.

Can Hermes write to Notion safely? Yes, if you scope it: a dedicated integration token granted to specific databases, write tools limited to append/update (no delete), and a human-review step for anything client-facing.

What does the VPS setup cost? A $5–10/month VPS runs a Hermes agent comfortably. The real cost is the wiring — gateway, systemd hardening, MCP registration — which is a day of work the first time.

Do I need Hermes specifically? No. The same MCP endpoint works with Claude, ChatGPT connectors, or any MCP-capable agent. Build the MCP layer once and the agent on top is swappable.

Want this wired into your operations — agent, MCP, and the Notion system underneath? See our AI agent setup service or book a call.