---
title: "Deploy Hermes Agent MCP"
description: "Give Hermes Agent new tools through MCP servers"
category: "AI/ML"
url: https://railway.com/deploy/deploy-hermes-agent-with-mcp-servers
---

# Deploy Hermes Agent MCP

Give Hermes Agent new tools through MCP servers

**[Deploy Hermes Agent MCP on Railway](https://railway.com/template/deploy-hermes-agent-with-mcp-servers)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/deploy-hermes-agent-with-mcp-servers/manifest.json

- **Creator:** onepush
- **Category:** AI/ML

## Template content

### hermes-agent

- **Image:** nousresearch/hermes-agent:v0.22.0@sha256:c69536a39e885b8943329bda68cdf44492458b96aa74a212239bde9d2aeb406a
- **Start command:** `sh -c "mkdir -p /opt/data && chown -R 10000:10000 /opt/data && exec /opt/hermes/docker/entrypoint-dispatch.sh hermes gateway run"`
- **Health check:** /health
- **Public domain:** Yes

## Documentation

# Deploy and Host self hosted Hermes Agent MCP (Self-Hosted AI Agent with MCP Tool Servers) on Railway

This template runs Hermes Agent as an always-on gateway that calls tools from MCP servers. It suits people who want GitHub or docs tools reachable from chat.

## About Hosting Hermes Agent MCP open-source software on Railway (self hosted Hermes Agent with MCP servers template)

This template runs one Hermes Agent service from the pinned nousresearch/hermes-agent:v0.22.0 image, with the Hermes home kept on the /opt/data volume.

## Why Deploy Hermes Agent MCP, the Claude Desktop alternative on Railway (Railway Free Trial)

Claude Desktop is a solid MCP client, but it runs on your laptop and only talks to Anthropic models. Railway's $5 trial covers a first look before you commit.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Hermes Agent MCP on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

### Railway vs Other Hosting Providers and VPS for Hermes Agent MCP self hosting

A VPS gives you control but leaves Docker, the volume, and restarts to you.

| Provider | What You Get with Railway | What You Get with the Other Provider |
| --- | --- | --- |
| DigitalOcean | A deployed Hermes Agent service with a persistent volume, a public domain, and a shell for editing config.yaml. | A Droplet with root access where you set up Docker, the firewall, and backups yourself. |
| AWS | One service running the pinned Hermes image, with no IAM or VPC setup before your first MCP call. | Fine-grained networking and scaling, but many more pieces to wire together. |
| Hetzner | A managed deploy with the volume and domain attached, so remote MCP servers are reachable without firewall rules. | Low cost and fast hardware, but you install Docker and open ports yourself. |

Pick a VPS if you enjoy server work, and Railway if you want your MCP tools live in chat without an ops weekend.

## Common Use Cases for hosted Hermes Agent MCP

- **GitHub issues and PRs from chat:** Point Hermes at a GitHub MCP server with a bearer token in an env var, then ask it to summarize open PRs or open an issue from a Telegram message while you're away from your desk.
- **Linear or ticket triage:** Connect a ticketing MCP server and have the agent list unassigned bugs each morning, tag them, and post a short digest to a Slack channel.
- **Docs and repo Q and A:** Add a remote docs-search MCP server so teammates can ask questions about internal runbooks and get answers grounded in the actual files.
- **Internal API tools behind a token:** Wrap an internal service in an MCP server, then reference its Authorization header through a ${VAR} placeholder so the secret never lands in config.yaml.
- **Read-only database queries:** Give the agent a read-only database MCP server with tools.include limited to query tools, so it can answer metric questions without any write access.

## Dependencies for Hermes Agent MCP Docker hosted on Railway

Hermes Agent MCP runs as one Railway service built from the official nousresearch/hermes-agent image, pinned to v0.22.0 by sha256.

### Deployment Dependencies for Managed Hermes Agent MCP Service (AI Agent)

- One Railway service running nousresearch/hermes-agent:v0.22.0 pinned by sha256
- A volume mounted at /opt/data so config.yaml and .env survive redeploys
- Port 8642 exposed, with health checks against /health
- One of OPENROUTER_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY, or a Nous Portal login
- Optional TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS for chat access to MCP tools

### Implementation Details for Hermes Agent MCP (Using Hermes Agent official docker image)

The start command creates /opt/data, chowns it to uid 10000 so the hermes user can write to a fresh volume, then execs entrypoint-dispatch.sh with hermes gateway run.

## How does Hermes Agent MCP compare against other ways to give an agent MCP tools

Hermes Agent is one way to give an agent MCP tools, and the others each win in different places.

### Hermes Agent vs Claude Desktop (Desktop MCP Client Alternative)

- **Where Hermes Wins:** The agent runs on your own server, so chat from Telegram, Discord or Slack can call the same MCP tools around the clock.
- **Model Choice:** Hermes works with any model provider you configure, while Claude Desktop uses Anthropic models only.
- **Where Claude Desktop Wins:** It's a polished desktop app with almost no setup, and it runs the MCP servers on your own machine.

### Hermes Agent vs OpenClaw (Self-Hosted Agent Gateway Alternative)

- **Shared Ground:** OpenClaw is also a self-hosted agent gateway with MCP support, so the two are close cousins in purpose.
- **Config Model:** Hermes keeps MCP servers in a single mcp_servers block in config.yaml, which is easy to edit from the Railway service shell.
- **Where OpenClaw Wins:** If your team already runs OpenClaw, switching costs more than it saves, and that is a fair reason to stay put.

### Hermes Agent vs Cursor MCP (IDE MCP Alternative)

- **Scope:** Cursor MCP gives tools to a coding session inside the IDE, while Hermes gives them to an always-on agent you can message from anywhere.
- **Where Cursor MCP Wins:** For editing code with the tools close at hand, the IDE is the better place to work.

### Hermes Agent vs Custom Function Calling (Build-It-Yourself Alternative)

- **Less Plumbing:** Hermes discovers each server's tools at startup and registers them like native tools, so you skip writing and hosting every tool yourself.
- **Filtering:** Per-server tools.include and tools.exclude lists keep the model from seeing tools it doesn't need.
- **Where Custom Code Wins:** If you need tight control over every call and its error handling, your own function calling gives you that precision, and Hermes can't match it.

## How to use Hermes Agent MCP (the OSS AI agent)?

1. Deploy the template and set one model provider key, such as OPENROUTER_API_KEY. Wait for /health to show healthy.

2. Open the Railway service shell. The Hermes home lives on the /opt/data volume.

3. Edit config.yaml there and add an mcp_servers entry with a url and headers:

```yaml
mcp_servers:
  github:
    url: "https://mcp.example.com/mcp"
    headers:
      Authorization: "Bearer ${GITHUB_MCP_TOKEN}"
    tools:
      include: ["search_issues", "get_pull_request"]
```

4. Store the token in a Railway variable named GITHUB_MCP_TOKEN. The ${VAR} placeholder resolves from the environment at connect time, so the secret stays out of the file.

5. Keep tools.include short. Models pick the wrong tool when the list is long.

6. Restart the service or run /reload-mcp, then ask Hermes in chat to search your open issues and confirm it calls the allowed tool.

## How to self host Hermes Agent MCP on other VPS Services (Hermes Agent self hosting guide)

Running Hermes Agent MCP on a plain VPS takes four steps. The MCP config lives in the Hermes home on that machine.

### Clone the Repository

Pull the source from GitHub and move into the folder.

```bash
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
```

### Install Dependencies

Run the install script, then the setup wizard to pick a model provider.

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup
```

### Configure Environment Variables

Keep tokens in `~/.hermes/.env` and reference them with `${VAR}` in `~/.hermes/config.yaml`.

```yaml
mcp_servers:
  github:
    url: "https://mcp.your-domain.com/mcp"
    headers:
      Authorization: "Bearer ${GITHUB_MCP_TOKEN}"
    tools:
      include: ["list_issues", "get_issue"]
```

Run `/reload-mcp` once the gateway is up.

### Start the Hermes Agent MCP Application

Start the gateway so Telegram, Discord, Slack or WhatsApp can reach the agent.

```bash
hermes gateway run
```

Railway handles the container build, the persistent volume and the public HTTPS domain, which a bare VPS leaves to you.

## Official Pricing of Hermes Agent MCP (Hermes Agent pricing)

Hermes Agent is open source under the MIT license, so the software itself costs nothing to use. There is no paid tier for the agent, and no price to quote.

## Hermes Agent MCP cloud vs self hosted comparison (Pricing, features, costs, and more)

Running Hermes Agent MCP on Railway trades a small monthly bill for not having to keep a box patched and online yourself.

### Monthly cost of self hosting Hermes Agent MCP on Railway

Expect roughly $5-10 per month for the Railway service at 512 MB to 1 GB of memory, plus whatever your model provider charges for tokens.

### System Requirements for Hosting Hermes Agent MCP on a VPS

Plan for at least 512 MB of RAM and enough disk for the Hermes home and any stdio server packages you install.

## Frequently Asked Questions (FAQs)

### Can I use a stdio MCP server on Railway?

Only if its command exists inside the container, such as npx or uvx installed in the image.

### Where does the mcp_servers config live?

It lives in config.yaml under the Hermes home on the /opt/data volume, so it survives redeploys.

### How do I hide dangerous tools from the model?

Set tools.exclude for that server to drop risky tool names, or use tools.include to allow only the few you want. The model only sees what passes the filter.

### Do OAuth MCP servers work on a headless server?

They are awkward because OAuth needs a browser callback on localhost.

### Can I use MCP tools from Telegram or Discord?

Yes, once the messaging gateway is running, the same registered MCP tools are available in chat.

### How many MCP tools is too many?

There is no hard limit, but past a few dozen the model starts picking the wrong one.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [Weaviate](https://railway.com/deploy/weaviate-1) — Vector database with hybrid search and an API key-protected API
- [Möbius v0.1 Personal AI OS](https://railway.com/deploy/mobius-v01-personal-ai-os) — Self-hosted AI agent that builds and runs apps for you, with memory.

Open this page in a browser: https://railway.com/deploy/deploy-hermes-agent-with-mcp-servers