MCP: Connect your IDE to Shoehorn
Shoehorn speaks the Model Context Protocol (MCP). That means your IDE’s AI assistant, Claude Desktop, Cursor, Claude.ai web, or any MCP-capable client, can read from your catalog without leaving your editor. Who owns a service, why a workload is unhealthy, what the runbook says. No copy-paste, no tab-switching.
This page is for developers using Shoehorn at your company.
What you can do
Section titled “What you can do”Ask an LLM running in your IDE things like:
- “Who owns
checkout-apiand which team is on the hook for it?” - “Why is
payments-workerunhealthy?” - “How many workloads per cluster are missing a network policy?”
- “Search docs for the payments deployment runbook, then answer from that page only.”
- “Fetch the runbook for
acme/paymentsand paste the text.”
Under the hood, the LLM calls Shoehorn’s read-only MCP tools. All of them are scoped to your tenant and none of them can write.
The tools
Section titled “The tools”This tool set is included in v0.7.0+. On an earlier release, query,
fetch, and describe_schema aren’t available yet; your server exposes
search_catalog, get_entity, list_entities, list_repositories,
get_repository, list_teams, get_team, and get_doc_content instead,
alongside list_zombies and whoami.
| Tool | What it does |
|---|---|
query |
Search, filter, group, and count across services, repositories, teams, people, workloads, clusters, scorecards, and docs |
fetch |
Get one thing by id, at the detail level you ask for, including a workload’s health summary |
describe_schema |
Show the model what’s queryable, per type, with worked examples |
list_zombies |
Find running workloads nothing depends on or has touched recently |
whoami |
Check your connection and return your team memberships, so the assistant can scope questions to the services you own |
Finding out what you can ask
Section titled “Finding out what you can ask”You don’t need to memorise any of this. Ask the assistant to call
describe_schema() with no arguments and it lists everything you’re
currently allowed to query: services and workloads, pod events, Helm
releases, GitOps sync status, connected resources, clusters, scorecards,
repositories, docs, teams, and people.
The list is yours, not everyone’s. It’s filtered by your role, so two people on the same tenant can get different answers from the same call. If something you expect is missing, that’s a permissions question for your admin, not a bug.
Once you know what you want, describe_schema({root: "resource"}) shows
that one’s fields, filters, and a couple of worked examples:
{ "from": "resource", "where": { "sub_type": "database" }, "aggregate": { "op": "count" } }Raw ArgoCD manifests (preview)
Section titled “Raw ArgoCD manifests (preview)”Included in v0.7.0+.
Shoehorn can keep a cleaned copy of each ArgoCD Application manifest, so the assistant can read the exact source repo, target revision and sync settings behind an app that’s misbehaving. This is a preview, and nothing is stored until you turn it on.
What gets stored. The Kubernetes agent sends the Application manifests it
already watches. Before a manifest leaves the cluster, the agent strips
managedFields, the last-applied-configuration annotation and anything shaped
like a secret. Secrets and RBAC objects are never stored: the agent doesn’t send
them, and Shoehorn rejects them if one arrives.
Turn it on.
- In the
shoehorn-k8s-agentchart,agent.manifestMirror.enabledis alreadytrue. It needsagent.gitops.argocd.enabledand adds no RBAC. - In the
shoehornchart, setMANIFEST_MIRROR_ENABLED: "true"underapi.env. Until you do, Shoehorn stores nothing and the assistant doesn’t seek8s_objectindescribe_schema.
Ask about it. query lists what’s mirrored, without the manifest bodies:
{ "from": "k8s_object", "where": { "kind": "Application", "namespace": "argocd" } }To read one manifest, the assistant calls fetch with the object’s id,
cluster/group/version/kind/namespace/name, and detail: "full-manifest".
The manifest comes back marked as untrusted content, so the assistant summarizes
it rather than following anything written inside it. Anyone who can see
Operations can query mirrored objects in their own tenant.
Setup in three steps
Section titled “Setup in three steps”1. Generate a token
Section titled “1. Generate a token”- Sign in to your Shoehorn instance.
- Open Profile → MCP (the direct link:
https://<your-shoehorn-host>/profile/mcp). - Pick an expiry (30 / 90 / 365 days, or Never) and click Generate PAT for MCP.
- Copy the token immediately, Shoehorn shows it only once. If you lose it, revoke it and generate a new one.
The token is scoped mcp:read. It can call every read-only MCP tool and
nothing else. Even if you paste it somewhere you shouldn’t, the worst a
leaker can do is read data you can already read.
2. Configure your client
Section titled “2. Configure your client”Each client has a config file or UI. Open the matching tab on
/profile/mcp, the page renders the JSON snippet with your token
already substituted in. Copy, paste, save.
::: tabs
Claude Code
Section titled “Claude Code”One command, no file to edit:
claude mcp add --transport http shoehorn https://<your-shoehorn-host>/mcp \ --header "Authorization: Bearer <YOUR_TOKEN>"Check it with claude mcp list, or ask Claude to call whoami.
Add --scope user to make it available in every project rather than just this
one.
Claude Desktop
Section titled “Claude Desktop”Edit your claude_desktop_config.json:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/claude/claude_desktop_config.json |
{ "mcpServers": { "shoehorn": { "url": "https://<your-shoehorn-host>/mcp", "headers": { "Authorization": "Bearer <YOUR_TOKEN>" } } }}Restart Claude Desktop. You should see “Shoehorn” appear in the tool palette (🔌 icon in the input area).
If Claude Desktop’s Advanced Settings UI only shows OAuth fields, edit the JSON file directly, headers-based auth still works even when the GUI doesn’t expose it.
Cursor
Section titled “Cursor”Edit ~/.cursor/mcp.json (or open Settings → Features → MCP):
{ "mcpServers": { "shoehorn": { "url": "https://<your-shoehorn-host>/mcp", "headers": { "Authorization": "Bearer <YOUR_TOKEN>" } } }}Restart Cursor. The Shoehorn tools will appear when you start a new chat with a tool-aware model.
Claude.ai (web)
Section titled “Claude.ai (web)”- Open
claude.ai→ Settings → Connectors → Add custom server. - Server URL:
https://<your-shoehorn-host>/mcp - Auth header:
Authorization: Bearer <YOUR_TOKEN> - Save. A “Shoehorn” connector will be available in any chat.
Older or community IDEs
Section titled “Older or community IDEs”If your MCP client doesn’t support remote servers natively, use the
mcp-remote npm shim:
{ "mcpServers": { "shoehorn": { "command": "npx", "args": [ "-y", "mcp-remote", "https://<your-shoehorn-host>/mcp", "--header", "Authorization: Bearer <YOUR_TOKEN>" ] } }}:::
3. Verify
Section titled “3. Verify”Ask your IDE’s LLM:
Call the Shoehorn MCP
whoamitool and tell me who I am.
You should see your user ID, tenant, token ID, and scopes echoed back. If you see that, the connection is live and every other tool will work too.
If the LLM says “I don’t have access to that tool”, the client hasn’t picked up the config. Restart it and check the config file path is correct for your OS.
Sign in with your company login
Section titled “Sign in with your company login”Included in v0.7.0+. On an earlier release, company login isn’t offered yet
on /profile/mcp, and a personal access token is the only way to connect.
Instead of pasting a token, your assistant can send you through your normal company login. You get the same access you’d get in the browser, there’s no long-lived secret sitting in a config file, and revoking someone in your identity provider revokes their MCP access too.
Personal access tokens keep working and stay the right answer for CI, where there’s nobody to open a browser.
Company login is on by default. An install that can’t work out its own audience
or public MCP address logs a warning and keeps serving personal access tokens
rather than failing to start. If you self-host and want the OAuth path off
entirely, set auth.mcp.enabled=false.
Which providers this works with
Section titled “Which providers this works with”| Provider | Company login over MCP |
|---|---|
| Zitadel | Yes. Register an app first. See below. |
| Okta | Yes, if your org has a custom authorization server. See below. |
| Microsoft Entra ID | No. Use a personal access token. |
Entra ID doesn’t support the standards this needs, and Microsoft has said dynamic client registration isn’t on their roadmap. This isn’t a gap we can close from our side, so on Entra use a token.
Tell Shoehorn about the app
Section titled “Tell Shoehorn about the app”Registering the app is half of it. Shoehorn needs the client ID too, or the setup page at /profile/mcp keeps offering personal access tokens and never mentions company login.
auth: mcp: clientId: "<the Client ID from your provider>" callbackPort: 8080The page checks for both the OAuth path being on and a client ID being set, because rendering a sign-in snippet without one would hand people a config that cannot work. Empty client ID, no company-login option, no error: that is the symptom to recognise if the page looks unchanged after you set everything else up.
Terraform users set mcp_oauth_client_id and mcp_oauth_callback_port.
callbackPort has to match the redirect URI you registered, exactly, port
included. Pick either provider’s setup below first, then come back and fill
these in.
Zitadel setup
Section titled “Zitadel setup”Your Zitadel admin does this once for everyone. Register an app, the same as Okta below. Zitadel supports dynamic client registration, but it doesn’t produce a token Shoehorn can use. There’s more on that at the end of this section if you want the detail.
Run Zitadel 2.48.2 or newer. Older versions can leave the project audience out of the token, and sign-in then fails without telling you why. This was last verified end to end on 4.17.1.
Register an app for MCP. Create a new one rather than reusing the app Shoehorn signs in with, so MCP access can be revoked on its own.
- In your project, Applications → New, type User Agent or Native
- Authentication method: PKCE. The app needs no secret.
- Redirect URIs:
http://localhost:8080/callback - Turn on Development Mode. Zitadel rejects plain-HTTP redirect URIs without it, and MCP clients redirect to a loopback address.
- Copy the Client ID.
Set the token type to JWT. This is the step people miss, and it’s the one that produces the most confusing failure.
On the app’s Token Settings, set Auth Token Type to JWT. Zitadel’s default is an opaque bearer token, which Shoehorn can’t read at all: it verifies signatures itself rather than calling back to Zitadel to introspect. Sign-in appears to succeed and every call afterwards fails.
The port in the redirect URI has to match the callback port your client uses. Any free port works as long as both agree.
A valid Zitadel token on its own doesn’t grant access. Shoehorn checks your role on every call, because Zitadel issues audience claims without checking what the holder is allowed to touch.
That’s the whole Zitadel setup. With the client ID in hand, skip past the Okta section to Configure your client.
Okta setup
Section titled “Okta setup”Your Okta admin does this once for everyone.
Check which authorization server you have first. In Okta, open
Security → API. A server listed there called default, with the audience
api://default, means you have API Access Management and company login will
work. If the only entry is your org authorization server, Okta can’t issue a
token Shoehorn is able to read, and no amount of configuration changes that.
Those orgs use a personal access token, which is the supported path for them
rather than a fallback.
Already on api://default? Consider adding a second authorization server just
for MCP, with its own audience. It costs nothing extra and keeps MCP tokens
from being interchangeable with your web app’s.
Register an app for MCP. Create a new app rather than reusing the one Shoehorn signs in with, so MCP access can be revoked on its own and shows up separately in your logs.
- Applications → Create App Integration → OIDC → Native Application
- Grant types: Authorization Code and Refresh Token. Without refresh, everyone signs in again every hour.
- Sign-in redirect URI:
http://localhost:8080/callback - Client authentication: None. The app uses PKCE and needs no secret.
- Assign the people who should have MCP access, then copy the Client ID.
Okta matches redirect URIs exactly. The port here has to match callbackPort
in the config below, and you can pick any free port as long as both agree.
Every OAuth client needs that client ID. Okta doesn’t allow anonymous dynamic client registration, which rules out an assistant registering itself.
You don’t need the okta_org claim at all, on either token type. Shoehorn
reads the tenant from its own configuration, for MCP and for web sign-in alike.
This page used to say the claim was still required for the browser path; that
stopped being true in August 2026. See
Okta integration.
Configure your client
Section titled “Configure your client”Set auth.mcp.clientId on the server first (see Tell Shoehorn about the
app) if you want /profile/mcp to generate
this for you with your values already filled in.
The two providers need different scopes. Okta wants openid offline_access.
Zitadel wants those plus a reserved scope naming your project ID, which is what
makes Zitadel put the right audience in the token. Leave it out and sign-in
succeeds, then every call is rejected.
Use add-json rather than add. claude mcp add has flags for the client ID
and callback port but none for scopes, so it can’t express this.
Zitadel:
claude mcp add-json --scope local shoehorn '{ "type": "http", "url": "https://<your-shoehorn-host>/mcp", "oauth": { "clientId": "<Client ID from the app you registered>", "callbackPort": 8080, "scopes": "openid offline_access urn:zitadel:iam:org:project:id:<PROJECT_ID>:aud" }}'Two different Zitadel values go in there. clientId is the application’s, and
<PROJECT_ID> is the project the application lives in. They look alike and
swapping them fails in a way the error message won’t explain. The project ID is
the same one the server has as ZITADEL_PROJECT_ID.
Okta:
claude mcp add-json --scope local shoehorn '{ "type": "http", "url": "https://<your-shoehorn-host>/mcp", "oauth": { "clientId": "<Client ID from the app you registered>", "callbackPort": 8080, "scopes": "openid offline_access" }}'--scope local keeps the server to the current project. Use --scope user to
get it everywhere.
Then sign in:
claude mcp login shoehornA browser opens, you log in with your provider, and the assistant stores the
token itself. Other clients take the same oauth block in their own config
file; the field names are identical.
The callbackPort has to match the redirect URI you registered with your
provider. Any free port works as long as both agree.
Working over SSH, or anywhere a browser can’t open? claude mcp login shoehorn --no-browser prints the URL instead. Open it wherever you do have a browser
and paste the redirect back.
Verify the same way as above: ask it to call whoami.
If sign-in fails
Section titled “If sign-in fails”“Dynamic Client Registration rejected (HTTP 403)” means no client ID
reached your assistant. Check the oauth block is in the config and that you
restarted the client.
“token owner is inactive or deleted” after a successful Okta login means Shoehorn matched your token to no user. Check that the person signing in has an active Shoehorn account and is assigned to the Okta app.
Older Shoehorn versions returned this when the tenant came from the okta_org
claim, because an Okta org string isn’t a Shoehorn tenant ID and the lookup
found nothing. Adding the claim made it worse rather than better. Upgrade if
you’re seeing this on every login.
A redirect URI mismatch from Okta means the registered URI and
callbackPort disagree. They have to match exactly, including the port.
Usage examples
Section titled “Usage examples”Natural prompts you can paste into Claude Desktop / Cursor / Claude.ai once connected:
“Who owns this service?”
Section titled ““Who owns this service?””“Using the Shoehorn tools, find the service
checkout-apiand tell me who owns it and which team is responsible.”
Your AI assistant will call fetch(entity, "checkout-api"), then usually
follow up with fetch(team, ...) on the owning team’s slug and
summarise.
“Show me the payments stack”
Section titled ““Show me the payments stack””“List all Shoehorn entities owned by the
paymentsteam.”
Your AI assistant calls query({from:"entity", where:{owner_team:"payments"}}).
“What are we running that nobody looks after?”
Section titled ““What are we running that nobody looks after?””“Use
list_zombiesto find workloads nothing has touched in 180 days.”
Your AI assistant calls list_zombies(inactive_days: 180). Every row is a running
Kubernetes workload that nothing depends on, with cluster components like
cilium and Argo CD already filtered out. Each row carries last_signal_at
and last_signal_kind (deploy, sync, change or push), which say what
the newest evidence was and where it came from, so the assistant can explain
why a workload is on the list instead of just naming it.
“Any issues with my apps in the last 24 hours?”
Section titled ““Any issues with my apps in the last 24 hours?””“Check my team’s services for problems since yesterday.”
Your AI assistant calls whoami to get your teams, queries workloads filtered to
those teams with their live signals (status, restarts, OOM kills, sync
state), then pulls recent warning events for their namespaces and matches
them back to your workloads.
“Why is this workload unhealthy?”
Section titled ““Why is this workload unhealthy?””“Use Shoehorn to figure out why
orders-apiis unhealthy in production.”
Your AI assistant resolves the workload with query, then calls fetch
at the health detail level. That returns one summary covering pod
events, GitOps sync state, config drift, and rollout status, and it digs
into detail only where something looks off.
“Audit one service”
Section titled ““Audit one service””“Give me a one-page report on
orders-api: who owns it and how it scored on the last governance scorecard.”
Your AI assistant calls fetch(entity, ...), then query against
scorecards filtered to the service.
“Search docs, then read the page text”
Section titled ““Search docs, then read the page text””“Using Shoehorn MCP, search docs for deployment runbooks for payments, then fetch the best matching page and answer from that source only.”
The normal flow is query on docs first, then fetch on the winning hit.
Snippets in query results are crops; the model fetches the page before
quoting from it.
“Am I connected?”
Section titled ““Am I connected?””“Call the
whoamitool.”
Returns your identity, useful whenever something feels off and you want to check the token is still valid.
Can the LLM change anything?
Section titled “Can the LLM change anything?”No. All MCP tools are read-only and annotated ReadOnlyHint: true in
the MCP protocol. Shoehorn’s server rejects any attempt to use this token
for write operations with HTTP 403. If you see “write” in a tool name,
that’s a bug, open an issue.
What data does the LLM see?
Section titled “What data does the LLM see?”Only data you can see. The token is scoped to your tenant and your user. If you can’t see a service in the Shoehorn UI, the MCP tool won’t return it either, Postgres row-level security handles this at the database layer.
Does my prompt go to Shoehorn?
Section titled “Does my prompt go to Shoehorn?”No. Your prompt goes to Anthropic (or whoever runs the LLM). The LLM
then calls Shoehorn tools on your behalf, sending only the tool arguments
(e.g. {"query": "checkout"}) over the network.
What does Shoehorn log about my tool calls?
Section titled “What does Shoehorn log about my tool calls?”Every MCP tool call is logged with your user ID, token ID, tenant ID, the tool name, and the duration. The arguments are not logged (so we don’t have a record of every query you ran), only the fact that a call happened. Raw tokens are never logged.
My token stopped working
Section titled “My token stopped working”Three likely causes:
- Token expired, regenerate it under Profile → MCP.
- Token revoked, check Profile → Security → Personal Access Tokens. Revoked tokens show with a strike-through. Generate a new one.
- Rate limit, if you’ve been chaining 30+ rapid tool calls (or
accidentally looped a prompt), you may hit the per-token rate limit.
Wait ~10 seconds and try again. If it keeps happening, ask your
platform admin to bump
MCP_RATE_LIMIT_BURST.
Tools stopped working after an upgrade
Section titled “Tools stopped working after an upgrade”Reconnect the MCP server in your client.
Your client caches the shape of each tool’s response when it first connects. An
upgrade that adds a field to a response makes a client still holding the old
copy reject it, usually with must NOT have additional properties. Nothing is
broken on either side. The client is just checking new responses against a
stale copy of the contract.
In Claude Code, run /mcp and reconnect. In other clients, restart it or
remove and re-add the server.
Shoehorn now publishes tool shapes that accept fields your client hasn’t seen, so upgrades from here on won’t need this.
Can I share my token with a teammate?
Section titled “Can I share my token with a teammate?”No. The token is scoped to you specifically, tool calls show up in the audit log as “user X called tool Y”. A shared token makes audit trails useless and violates most security policies. Ask your teammate to generate their own; it takes 10 seconds.
Can I use this outside an IDE?
Section titled “Can I use this outside an IDE?”Yes, the /mcp endpoint is just HTTP. You can call it with curl, Python,
or any HTTP client that speaks JSON-RPC 2.0. See the verify example:
curl -s -X POST https://<your-shoehorn-host>/mcp \ -H "Authorization: Bearer <YOUR_TOKEN>" \ -H "Content-Type: application/json" \ -H "Accept: application/json, text/event-stream" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}'But it’s much more useful from an IDE because the LLM chooses which tools to call based on your natural-language query.
Is my team’s data visible to other tenants?
Section titled “Is my team’s data visible to other tenants?”No. Shoehorn is multi-tenant by design and enforces tenant isolation at the database layer. Your token can only read rows in your own tenant, and this is tested under every MCP release.
Rotating your token
Section titled “Rotating your token”Good hygiene: rotate every 90 days.
- Generate a new token at Profile → MCP.
- Update your IDE config, paste the new token where the old one was.
- Restart the IDE to pick up the new token.
- Confirm with
whoami. - Revoke the old token at Profile → Security → Personal Access Tokens (click the trash icon next to it).
Doing it in that order, new first, old last, avoids a gap where neither works.
Limits
Section titled “Limits”| Limit | Value | Why |
|---|---|---|
| Max results per call | 200 entities/teams/etc. | LLM context windows are finite; 5,000-row dumps are always wrong |
| Rate limit per token | 5 requests/sec, burst 30 | Guards against runaway agent loops and leaked-token blast radius |
| Search query length | 253 characters | Anything longer is almost certainly adversarial |
Facets per group_by |
64, or 1 for docs | The widest thing you can query has 17 fields. Docs counts one facet at a time. |
| Token max lifetime | 1 year (configurable at creation) | Hygiene, rotate anyway |
These are Shoehorn-side safeguards. They shouldn’t affect legitimate use; if they do, ask your platform admin.
What’s next
Section titled “What’s next”- Write tools, out of scope at v0. If you want to trigger a Forge workflow from your IDE, that’s on the post-beta roadmap.
- OAuth sign-in, off by default while we verify it against each identity provider we support. Once it’s on for your instance, clients that require OAuth (like claude.ai custom connectors) can sign in through your IdP instead of a pasted token. PATs stay either way; they remain the right choice for CI, scripts, and clients that don’t speak OAuth.
Running an SRE agent too?
Section titled “Running an SRE agent too?”If you use HolmesGPT to investigate incidents, it can read this same server. Holmes works out why something broke; Shoehorn tells it what the thing is, who owns it, and where the runbook lives.
Got feedback? Open an issue, or drop it in #shoehorn-feedback on your
company’s Slack.