Published on

TIL: an MCP header with ${VAR} reads the agent .env, not your shell

tilmcpdebuggingai-tooling
Authors

An MCP server returned 401 on every call. The API key was fine.

I proved that first by calling the vendor API directly with the key from my shell. 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:

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

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 things 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. Do not print either one.
Discuss on X