Integrates with a local Hermes Gateway API, enabling AI agents to delegate tasks to a Hermes AI agent with support for session continuity and profile selection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hermes-mcp-bridge Search for MCP protocol documentation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A zero-friction stdio MCP bridge connecting Cursor Desktop to a local Hermes Agent — no OAuth, no tunnels, no Dynamic Client Registration.
Cursor Desktop hermes-mcp-bridge Hermes Gateway
┌──────────────┐ stdio ┌─────────────────────┐ HTTP ┌──────────────┐
│ mcp.json │ ─────────→ │ FastMCP │ ───────→ │ 127.0.0.1 │
│ command: │ │ ├ hermes_ask() │ Bearer │ :8642 │
│ /home/... │ ←───────── │ ├ hermes_check() │ ←─────── │ /v1/chat/ │
└──────────────┘ stdio │ ├ hermes_cancel() │ JSON │ completions │
│ └ hermes_reset() │ └──────────────┘
└─────────────────────┘
X-Hermes-Session-Id → REPL context
|
| |
Transport | Streamable HTTP | stdio |
Auth | OAuth 2.1 + DCR | Bearer header |
External deps | cloudflared / ngrok | none |
Process model | Standalone daemon | Cursor subprocess |
Deployment files | 5 configs + systemd unit | 2 files |
Related MCP server: cursor-mcp-server
The bridge connects to the same Hermes profile your gateway is serving. It inherits everything that profile has loaded — skills, memory, tools, sessions.
You can pick which profile to use in two ways:
Method | What you do | When to use |
Set a default | Edit | You mostly use one profile |
Mention it in chat | Say "Use Hermes with the default profile to…" in the Cursor chat input | You switch profiles often |
Neither requires touching mcp.json or restarting Cursor.
# ~/.config/hermes-mcp-bridge/config.toml
model = "general_researcher" # ← used when no profile arg is passedThe hermes_ask tool exposes an optional profile parameter. Just mention
which profile you want — Cursor's LLM reads the tool signature and passes it.
┌─────────────────────────────────────────────────────────┐
│ You say in Cursor │
├─────────────────────────────────────────────────────────┤
│ "Use Hermes with the default profile to send an email" │
│ → hermes_ask(prompt="send an email", │
│ profile="default") │
│ │
│ "Ask Hermes to search arXiv for MCP papers" │
│ → hermes_ask(prompt="search arXiv...") │
│ # no profile → uses config.toml default │
└─────────────────────────────────────────────────────────┘No mcp.json changes, no config edits, no restart. Just say the profile name.
curl -s http://127.0.0.1:8642/v1/models \
-H "Authorization: Bearer change...-dev"
# → {"data": [{"id": "general_researcher", ...}, {"id": "default", ...}]}If your gateway only runs one profile, only one
idappears. Start additional gateway instances on different ports to serve multiple profiles simultaneously.
mlennie/hermes-mcp v0.4.0 hits three real-world blockers:
OAuth 2.1 demands an HTTPS tunnel — even when Cursor and Hermes run on the same machine.
No Dynamic Client Registration support — mcp-remote crashes with Incompatible auth server.
Cursor's localhost OAuth callback is broken — its built-in MCP HTTP client returns ERR_EMPTY_RESPONSE on localhost.
This bridge drops the HTTP transport layer entirely, runs as a stdio subprocess, and sidesteps all three.
git clone https://github.com/<your-org>/hermes-mcp-bridge.git
cd hermes-mcp-bridge
uv tool install --editable .mkdir -p ~/.config/hermes-mcp-bridge
cat > ~/.config/hermes-mcp-bridge/config.toml << 'EOF'
api_url = "http://127.0.0.1:8642"
api_key = "change-me-local-dev" # must match API_SERVER_KEY in ~/.hermes/.env
model = "general_researcher"
timeout_seconds = 300
EOF
chmod 600 ~/.config/hermes-mcp-bridge/config.tomlAdd to ~/.cursor/mcp.json:
{
"mcpServers": {
"hermes": {
"command": "/home/nirvana/.local/bin/hermes-mcp-bridge"
}
}
}Settings → MCP → hermes should show connected.
Tool | Signature | Purpose |
|
| Delegate a task to Hermes Agent |
|
| Poll async job status (stub) |
|
| Cancel an async job (stub) |
|
| Clear the job queue (stub) |
The last three are kept for API parity.
hermes-mcp-bridgeruns synchronously —hermes_askblocks until the full Agent response is ready.
Hermes remembers what you told it earlier — just keep talking in the same
Cursor chat. Cursor automatically reuses the same session_id across turns.
┌─────────────────────────────────────────────────────────┐
│ You say in Cursor │
├─────────────────────────────────────────────────────────┤
│ "Use Hermes to remember that my lucky number is 42" │
│ → Hermes remembers 42 │
│ │
│ "Ask Hermes what my lucky number is" │
│ → Hermes answers 42 │
│ (same session_id — context preserved) │
└─────────────────────────────────────────────────────────┘The bridge passes session_id through as the X-Hermes-Session-Id HTTP header.
The gateway uses it to maintain context across calls.
No special syntax. No session IDs to track. Just talk normally — Hermes remembers.
~/.config/hermes-mcp-bridge/config.toml
Key | Default | Description |
|
| Hermes Gateway HTTP API address |
| — | Must match |
|
| Must match a model ID from gateway |
|
| Max wait per |
Environment variable overrides (higher priority): HERMES_BRIDGE_API_URL, HERMES_BRIDGE_API_KEY.
All network traffic is confined to the 127.0.0.1 loopback interface.
The API key lives in ~/.config/hermes-mcp-bridge/config.toml (mode 600).
The repository itself contains no keys, secrets, or credentials.
Cursor spawns the bridge via stdio — no ports are exposed.
Apache-2.0
Delegate a task to Hermes Agent on this user's machine.
Use for things the calling LLM cannot do directly: scheduling cron jobs, browser-driven web search, sending email, creating/editing local documents, anything that should persist after this chat ends.
Args: prompt: Natural-language instruction for Hermes. session_id: Optional. Pass the same id across multiple calls in one chat to let Hermes remember prior steps (draft → refine → save). profile: Optional. Hermes profile to use (e.g. 'default', 'general_researcher'). Overrides the model in config.toml. Discover available profiles via the gateway's /v1/models endpoint.
Returns: Hermes's final answer text.
Inputs: prompt (required), profile, session_id. Returns: result
Not implemented. Kept for API parity with hermes-mcp.
Inputs: job_id (required). Returns: result
Not implemented. Kept for API parity with hermes-mcp.
Inputs: job_id (required). Returns: result
Not implemented. Kept for API parity with hermes-mcp.
Inputs: no named parameters. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 4 tools
All four tools have distinct names and clear descriptions. The three non-functional tools are explicitly marked as 'Not implemented', so an agent can easily distinguish the single functional tool from the stubs.
All tool names follow a consistent 'hermes_verb' pattern with imperative verbs (ask, cancel, check, reset), which is predictable and systematic.
With only one functional tool out of four, the effective tool count is very low for a server that claims to handle diverse tasks like scheduling, browsing, and email. The three stubs inflate the count without adding value.
The server is missing core lifecycle operations: there is no way to cancel a task, check its status, or reset a session, even though stubs for these exist. The single 'ask' tool cannot cover the full intended scope.
Real-time chat for AI agents. Claude Code, Cursor, Cline and Codex join channels over MCP.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Real-time chat hub for AI agents — Claude Code, Cursor, Cline, Codex over MCP or REST.
