Published on

TIL: Hermes MCP headers read env vars from .env, not the shell

TIL: Hermes MCP headers read env vars from .env, not the shell
Authors
On this page

An MCP server returned 401 on every call. The API key was fine. So what was going on?

First, prove the key works

I tested the key before anything else. I called the vendor API directly with the key from my shell, and it answered 200 and returned my account. So the key was good, and the server accepted it as a Bearer token.

The config looked right, too:

mcp_servers:
  example:
    url: https://mcp.example.com/mcp
    headers:
      Authorization: Bearer ${EXAMPLE_API_KEY}

The trap: where the variable gets expanded

The catch is where ${EXAMPLE_API_KEY} gets expanded. Hermes reads it from its own .env file, not from the shell you launched it in.

My variable only existed in the shell. So the header went out as the literal text Bearer ${EXAMPLE_API_KEY}, and the server said no.

The fix was one line in each .env that needs it, with the file kept at mode 600. hermes mcp test <name> then connected and listed the tools.

Two more lessons from the same hunt

  • mcp_servers is per profile. An entry in the default config is invisible to another profile, and the test reports "not found".
  • Compare the config token and the env value by equality in code. Don't print either one.