[2026] Complete Guide to Setting Up OpenRouter MCP with Hermes Agent! Up to 24x Cost Reduction

Setting up OpenRouter MCP with Hermes Agent lets your AI agent dynamically select the best models in real time. It only takes three lines of YAML.

What You'll Learn in This Article

What OpenRouter MCP is
How to add an MCP server to Hermes Agent (config.yaml editing)
How to verify your setup
Practical usage and real-world examples
Common issues and troubleshooting

What Is OpenRouter MCP?

OpenRouter MCP (Model Context Protocol) is an MCP server provided by OpenRouter. Connecting it to Hermes Agent gives you access to the following tools:

list-models — Get a list of available models
get-model — Get detailed information on a specific model
list-daily-model-rankings — Get daily model rankings
list-benchmarks — Get benchmark data
send-message — Send a message to a model and test it
get-credits — Check your remaining credits
get-generation — Retrieve past generation results

With these tools, Hermes Agent can dynamically select the best model for each task while referencing real-time pricing, benchmarks, and rankings.

OpenRouter's X account has reported cases of up to 24x cost reduction using this MCP integration.

Prerequisites

Before you start, make sure you have:

✅ Hermes Agent installed (if not, see hermes-agent.nousresearch.com)
✅ An OpenRouter account
✅ An OpenRouter API key

You can get your API key at openrouter.ai/keys.

Setup Instructions (3 Steps)

Step 1: Open config.yaml

Hermes Agent's configuration file is located at:

~/.hermes/config.yaml

Open this file in a text editor:

nano ~/.hermes/config.yaml

code ~/.hermes/config.yaml

Step 2: Add MCP Server Configuration

Add the following configuration to the end of config.yaml:

mcp:
  servers:
    openrouter:
      url: https://mcp.openrouter.ai/
      auth:
        bearer: ${OPENROUTER_API_KEY}

Key points:

${OPENROUTER_API_KEY} is automatically read from ~/.hermes/.env
If you already have OPENROUTER_API_KEY set, it works as-is
If you haven't set it yet, add the following to ~/.hermes/.env:
```
OPENROUTER_API_KEY=sk-or-v1-your-api-key
```

Step 3: Verify the Setup

To apply the configuration, launch Hermes Agent and run:

hermes mcp list

If you see output like this, you're all set:

MCP Servers:
  - openrouter (connected): https://mcp.openrouter.ai/
    tools: list-models, get-model, list-daily-model-rankings, list-benchmarks, send-message, get-credits, get-generation

If it doesn't connect, try the /reload-mcp command as well.

How to Use

Once configured, MCP tools are automatically available just by giving instructions in your Hermes chat.

Basic Usage

Simply say "Check OpenRouter MCP for the best model," and Hermes will automatically call the tools and return results:

You: What's the best and cheapest model for this task?

Hermes: Let me check OpenRouter MCP...
(runs list-models + list-benchmarks automatically)
→ "DeepSeek V4 Flash offers the best cost-performance at $0.42/million tokens"

Usage Examples

Example 1: Find the Best Cheap Model for Coding

You: Use the list-models tool and tell me the top 5 affordable models strong at coding

Example 2: Compare Model Quality and Cost

You: Compare GPT-5.6 Sol and Claude Fable 5 in terms of quality and cost

Example 3: Test a Model in Practice

You: Test DeepSeek V4 Flash with send-message and check its actual response quality

Example 4: Budget Management

You: Check my credit balance for this month

Tool Reference

Here are the main tools available through OpenRouter MCP:

Tool Name	Function	Use Case
list-models	Get all models list	See what models are available
get-model	Get details on a specific model	Check model specs and pricing
list-daily-model-rankings	Get daily rankings	See today's popular models
list-benchmarks	Get benchmark data	Compare model performance
send-message	Send a message to a model	Test models in practice
get-credits	Check remaining credits	Budget management
get-generation	Retrieve past generations	Review history

These tools are prefixed with mcp_openrouter_ inside Hermes. For example, list-models is recognized as mcp_openrouter_list-models.

Choosing an Authentication Method

OpenRouter MCP supports two authentication methods:

Bearer Authentication (Recommended)

For always-on agents like Hermes Agent, Bearer authentication is the most stable option:

auth:
  bearer: ${OPENROUTER_API_KEY}

Uses your standard OpenRouter API key. No need to worry about key expiration.

OAuth Authentication (Not Recommended)

auth:
  oauth: true

Issues a dedicated key valid for 7 days. Requires browser-based authentication, making it unsuitable for long-running CLI-based Hermes setups.

Advanced Configuration

Tool Filtering

If you want to enable only specific tools, use include or exclude:

mcp:
  servers:
    openrouter:
      url: https://mcp.openrouter.ai/
      auth:
        bearer: ${OPENROUTER_API_KEY}
      tools:
        include:
          - list-models
          - get-model
          - send-message

This lets you limit which tools Hermes can use. Narrowing down to only the tools you need helps prevent unnecessary API calls.

FAQ

Q1: I set it up but the MCP isn't recognized

Check with hermes mcp list. If you see errors, verify that the API key in .env is correct. Try /reload-mcp if needed.

Q2: Do I need to restart?

No. Changes are reflected immediately with hermes mcp list. If they still don't appear, try /reload-mcp.

Q3: What's the difference between Bearer and OAuth?

Bearer is recommended. OAuth requires re-authentication every 7 days and isn't suited for long-running agents like Hermes.

Q4: How much can I save on costs?

OpenRouter has reported up to 24x cost reductions in their case studies. You can save even more by leveraging free models.

Q5: Why do tools get a prefix?

So Hermes can identify which MCP server they belong to. The server name is added as a prefix, like mcp_openrouter_list-models.

Q6: Can I use it alongside other MCP servers?

Absolutely. You can configure multiple MCP servers simultaneously.

Reference Links

This article is based on information as of July 13, 2026. Please check the official documentation for the latest updates.