Adding an MCP-capable agent (Claude Code, VS Code, Cursor, OpenCode, etc.) to
Steerholm is two steps: register it to get its access key, then point it at
Steerholm. From then on it acts on the action plane as that agent, and every
request is checked against its policy before anything reaches a server.
An agent sees no tools until you also grant it access — that’s a separate
step, covered in Managing access. 1. Register the agent
This prints an access key (steer_sk_…) once — save it now; it’s the only time
the full key is shown. holm show agent my-agent shows only the key prefix. Lost
it? Issue a new one with holm rotate agent my-agent (the old key stops working
immediately).
2. Point the agent at Steerholm
Every agent connects the same way, with two things:
- Endpoint —
http://127.0.0.1:4767/mcp
- Header —
Authorization: Bearer steer_sk_...
The rest is just where each agent keeps its config and what it names the entry.
Claude Code
VS Code (Copilot)
Cursor
OpenCode
Add the server with the CLI. Run this from your project — it writes to the
project’s local scope by default; add --scope user to make it available in
every project:To share the server with a team, commit an .mcp.json at your project root
instead:The "type": "http" field is required. Claude Code reads a url entry
with no type as a stdio server and skips it.
Put the config in .vscode/mcp.json in your workspace (or your user profile
via the MCP: Open User Configuration command). The top-level key is
servers:MCP tools are available in Copilot Chat’s Agent mode. To avoid committing
the key, replace the header value with an input reference such as
Bearer ${input:steerholm-key} and let VS Code prompt for it once. See the
VS Code MCP docs
for the input-prompt syntax. Put the config in ~/.cursor/mcp.json (global, every project) or
.cursor/mcp.json at your project root. The top-level key is mcpServers:Cursor resolves ${env:VAR} inside headers, so you can keep the key out of
the file with "Authorization": "Bearer ${env:STEERHOLM_KEY}". See the
Cursor MCP docs. Put the config in opencode.json at your project root (or the global
~/.config/opencode/opencode.json). Remote servers live under the mcp key
with "type": "remote":OpenCode supports {env:VAR} substitution in headers, so you can write
"Authorization": "Bearer {env:STEERHOLM_KEY}". See the
OpenCode MCP docs. Steerholm binds to loopback over plain HTTP. Use the host and port from
holm serve if you changed the defaults.
Copying the key into the agent is the current manual step. A future release
will set this connection up for you (and launch agent sessions directly) — the
model stays the same, the copy-paste goes away.
3. Verify
From Steerholm’s side, confirm the agent is registered and holds a key:
In the agent itself, the Steerholm connection should come up connected, with no
auth error. It lists only the tools its policy allows — so a freshly added agent
with no grants connects successfully but sees nothing yet. Grant it a server (see
Managing access) and its tools appear.
If the agent reports an authentication or connection error, head to
Troubleshooting.
Rotate a key
Rotating issues a new access key and keeps all of the agent’s grants. The old
key stops working immediately, so update the agent’s config with the new key
afterward:
Remove an agent
Removes the agent, revokes its key, and deletes its policy:
