HolmesGPT (included in v0.7.0+)
HolmesGPT is an open-source agent that investigates production incidents. It reads logs, metrics, and live cluster state, then works out why something broke.
It’s good at that and Shoehorn doesn’t try to compete with it. What Holmes can’t tell you is what the broken thing actually is: which service it belongs to, which team owns it, how critical it is, or where the runbook lives. Shoehorn holds all of that.
Connect the two and Holmes investigates while Shoehorn answers the context questions. This page sets that up.
What Shoehorn adds to an investigation
Section titled “What Shoehorn adds to an investigation”| Question | Who answers it |
|---|---|
| Why is this pod crashing? | HolmesGPT (logs, metrics, live state) |
| What service is this, and who owns it? | Shoehorn |
| Is this tier-1 or a scratch workload? | Shoehorn |
| Where’s the runbook? | Shoehorn |
| Is it deployed the same way in our other clusters? | Shoehorn |
| What else does this team own? | Shoehorn |
Shoehorn holds no logs and no metrics. When an answer needs them, it returns links rather than guessing. That’s Holmes’ half of the job.
Before you start
Section titled “Before you start”- HolmesGPT running, either through the Robusta chart or standalone.
- A Shoehorn host reachable from your cluster.
- Permission to edit your Holmes Helm values.
1. Create a Shoehorn token
Section titled “1. Create a Shoehorn token”In Shoehorn, go to Profile > MCP and generate a token. It needs the
mcp:read scope, which is the default and is read-only. The MCP surface can’t
change anything in Shoehorn. Neither can this token.
Pick HolmesGPT in the client list and the page builds the config below with your host and token already filled in.
2. Store the token as a secret
Section titled “2. Store the token as a secret”Holmes reads its config from a values file you’ll probably commit to git. Put the token in a Kubernetes secret instead:
kubectl create secret generic shoehorn-mcp -n robusta --from-literal=token='shp_svc_YOUR_TOKEN_HERE'Use whichever namespace Holmes runs in.
3. Add Shoehorn to your Holmes values
Section titled “3. Add Shoehorn to your Holmes values”holmes: additionalEnvVars: - name: SHOEHORN_MCP_TOKEN valueFrom: secretKeyRef: name: shoehorn-mcp key: token mcp_servers: shoehorn: description: "Shoehorn: service ownership, runbooks, scorecards, and Kubernetes workload health" config: url: "https://shoehorn.example.com/mcp" mode: streamable-http headers: Authorization: "Bearer {{ env.SHOEHORN_MCP_TOKEN }}"On the standalone HolmesGPT chart, drop the holmes: key and start at
additionalEnvVars:.
Then apply it:
helm upgrade robusta robusta/robusta -f values.yaml4. Check it worked
Section titled “4. Check it worked”Ask Holmes something only Shoehorn can answer:
Who owns the checkout service, and what's its runbook?If the connection is live, Holmes calls Shoehorn’s whoami and query tools
and comes back with the owning team. If it says it has no way to look that up,
the server didn’t load. Check the Holmes pod logs for the MCP connection and
confirm the secret is mounted.
What Holmes can now reach
Section titled “What Holmes can now reach”Shoehorn exposes three tools: describe_schema, query, and fetch. Holmes
discovers the rest on its own, but these are the calls that matter during an
incident.
The health bundle. One call returns everything Shoehorn knows about a workload, assembled server-side:
fetch(entity, "k8s-default-deployment-podinfo", detail:"health")That’s per-cluster status and any deviating cluster, container issues, restart counts, right-sizing against p95 usage, network policy verdict, GitOps and Helm state, connected risk, and recent events. It’s deterministic and costs one call instead of six.
Events are labelled with their age. Kubernetes keeps events long after
they stop mattering, and a month-old ImagePullBackOff on a currently-healthy
workload will fool an agent into naming a resolved incident as the root cause.
The bundle marks each event with is_current and adds a note when nothing in
the set is live: “They describe what happened, not what is happening.” That’s
the difference between useful history and a confident wrong answer.
Ownership and docs. query({from:"entity", ...}) resolves a workload to a
service and its owning team. query({from:"docs", search:"checkout"}) finds
the runbook. When a workload has no runbook, the bundle says so explicitly
rather than returning nothing.
Cross-cluster comparison. Holmes investigates the cluster it runs in. Shoehorn holds every connected cluster. That turns “is this configured differently somewhere else” from an impossible question into one query.
Permissions
Section titled “Permissions”The token carries your permissions, not an admin’s. Every call runs through the
same Cerbos policies and row-level security as the web app. Holmes sees
exactly what the token’s owner would see. Roots the token can’t read don’t
appear in describe_schema at all.
Event messages and document text come from outside Shoehorn. Both are marked
untrusted_content. Anyone who can make a pod emit an event can write text
into an agent’s context. Holmes should treat those sections as data, not
instructions.
Related
Section titled “Related”- MCP: connect your IDE to Shoehorn for the same server from an editor
- HolmesGPT MCP documentation