Skip to main content
Most problems fall into one of a few buckets. Start with the two commands that tell you the most:

​
My tool connects but shows no tools

This is the most common first-run issue. Work through it in order:
1

Check the agent has grants

A brand-new agent is default-deny — it sees nothing until you grant it. Run holm show agent <name>; if it says none granted, add access with holm grant <agent> <server>.
2

Check the server is running

Run holm show server <name>. If the status is stopped or the daemon is down, start it with holm start (or holm status to check). Adding a server tells a running daemon to start it automatically, so if it isn’t running, the daemon is probably down.
3

Check the server didn't fail to start

If holm show server <name> reports failed, it prints the error — usually a bad --command (wrong path, missing npx, etc.). Fix the command: holm remove server <name> then holm add server <name> --command "...".
4

Reconnect the tool

Some tools only fetch the tool list when they first connect. If you granted access after connecting, reconnect (or restart) the tool so it re-lists tools.

​
401 Unauthorized

The Bearer token is missing, malformed, or not a valid access key.
  • Use the full access key (steer_sk_...), not the truncated prefix shown by holm show agent. The full key is only printed once, by holm add agent / holm rotate agent — if you lost it, rotate to get a new one: holm rotate agent <name>.
  • If you rotated the key, the old one stops working immediately — update the tool with the new key.
  • If you removed and re-created the agent, its old key is dead even if the name is the same.

​
The daemon isn’t running

The daemon runs as a per-user service that starts at login. On a headless or SSH-only box where you never log in graphically, it may not start on its own — run holm start, or run it in the foreground for debugging with holm serve (logs go to stderr).

​
Port already in use

If holm serve reports the port is taken, another Steerholm instance (or some other process) is on 127.0.0.1:4767. Stop the other one, or bind a different port with holm serve --port <port> (and point the agent at the new port).

​
”Server ‘X’ is not currently added” when granting

holm grant warns when the server name isn’t registered yet. Grants are allowed to reference a not-yet-added server, but usually this means a typo or a missing holm add server. Check holm list servers.

​
A tool call returns SERVER_UNAVAILABLE (-31002)

The downstream MCP server crashed or is unreachable. Check holm show server <name> for a failed state and its error, then fix the command and re-add it. The daemon also retries failed servers periodically, so a transient failure may clear on its own. See Error codes for the full list.