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 documentation text directly from Shoehorn without leaving your editor. No copy-paste, no tab-switching, no digging through the web UI just to paste markdown into chat.

This page is for developers using Shoehorn at your company. If you’re an operator or SRE wiring the server up in a Helm chart, see MCP setup for operators instead.

What you can do

Ask an LLM running in your IDE things like:

“Search docs across the tenant for ‘runbook deployment’ and show the best matches.”
“Fetch the runbook for acme/payments and paste the text.”
“Open docs/onboarding.md from acme/payments and summarise it.”
“Read the deployment guide from Shoehorn MCP and tell me the exact steps.”
“Pull the docs page text for this repo so you can answer from the source.”

Under the hood, the LLM can call Shoehorn’s read-only MCP tools. For docs, the important one is get_doc_content: it returns the actual page text from the indexed docs experience. All tools are scoped to your tenant and none of them can write.

Docs tools that matter

Tool	What it does
`search_docs`	Search indexed docs across the tenant, optionally filtered by repo or category
`get_doc_content`	Fetch one docs page by repo/ref/path and return its text
`whoami`	Verify your MCP auth if the client setup looks wrong

If your goal is “give the model the actual documentation text”, get_doc_content is the final retrieval step. search_docs is the discovery step that lets the model find the right doc across the tenant first.

Setup in three steps

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

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 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

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)

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

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

Ask your IDE’s LLM:

Call the Shoehorn MCP whoami tool 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.

Usage examples

Natural prompts you can paste into Claude Desktop / Cursor / Claude.ai once connected:

“Who owns this service?”

“Using the Shoehorn tools, find the service checkout-api and tell me who owns it and which team is responsible.”

Claude will call get_entity("checkout-api"), then usually follow up with get_team(...) on the owning team’s slug and summarise.

”Show me the payments stack”

“List all Shoehorn entities owned by the payments team.”

Claude calls list_entities(owner="payments").

”Which repos haven’t been touched?”

“Use list_zombies to find catalog entities that haven’t been deployed in 180 days and are still running workloads in Kubernetes.”

Claude calls list_zombies(inactive_days: 180) and sorts/filters by K8sReplicas > 0 from the response.

”Audit one service”

“Give me a one-page report on orders-api: who owns it, how it scored on the last governance scorecard, any open CVEs.”

Claude fans out three tool calls: get_entity, get_scorecard, list_vulnerabilities(service="orders-api").

”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 search_docs first, then get_doc_content once the model has the repo and markdown path it wants.

”Am I connected?”

“Call the whoami tool.”

Returns your identity, useful whenever something feels off and you want to check the token is still valid.

FAQ

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?

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?

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?

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

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.

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?

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?

No. Shoehorn is multi-tenant by design, Postgres row-level security policies enforce 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

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

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
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

Vulnerabilities, workloads, scorecards, cost, these tools register on every Shoehorn instance, but return {available: false} until the upstream features are enabled. Check back after your platform team ships CVE-lens, right-sizing, and scorecard-trendlines.
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 2.1 / PKCE, replaces the static PAT flow for public-facing deployments. Internal/team deployments will keep PAT as an option.

Got feedback? Open an issue, or drop it in #shoehorn-feedback on your company’s Slack.