# MCP server

`shruwd-mcp` is a local [MCP](https://modelcontextprotocol.io) server. It gives an AI
assistant tools to set up a brand, add prompts and competitors, read how the brand appears
in AI answers, and act on findings.

It runs on your machine over stdio and talks to the API with your key. There is no hosted
server. Clients that find servers from a site can read its install and configuration from
[`/.well-known/mcp.json`](https://shruwd.io/.well-known/mcp.json).

## Prerequisites

An API key from **Account → API keys**. A key is bound to one workspace and acts with your
role in it: reads need `viewer`, writes `editor`, creating or archiving a brand `owner`,
and minting an ingest token `admin`. To work across several workspaces, mint a key in each
and add one server entry per workspace. See [Roles](https://shruwd.io/docs/api/api-overview.md).

## Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "shruwd": {
      "command": "npx",
      "args": ["-y", "shruwd-mcp"],
      "env": { "SHRUWD_API_KEY": "sh_live_…" }
    }
  }
}
```

## Claude Code

```bash
claude mcp add shruwd -e SHRUWD_API_KEY=sh_live_… -- npx -y shruwd-mcp
```

## Cursor

In `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "shruwd": {
      "command": "npx",
      "args": ["-y", "shruwd-mcp"],
      "env": { "SHRUWD_API_KEY": "sh_live_…" }
    }
  }
}
```

## Environment

| Variable | |
|---|---|
| `SHRUWD_API_KEY` | Required |
| `SHRUWD_API_URL` | Optional. Defaults to `https://shruwd.io/api/v1` |

## Tools

| Tool | Does |
|---|---|
| `shruwd_get_workspace` | Plan, entitlements, usage, brands. Start here |
| `shruwd_list_brands` · `shruwd_get_brand` · `shruwd_create_brand` · `shruwd_update_brand` · `shruwd_archive_brand` | Brands. Creating one also creates its self entity and first measurement. Creating and archiving need `owner` |
| `shruwd_list_prompts` · `shruwd_add_prompts` · `shruwd_update_prompt` · `shruwd_remove_prompt` | The questions asked of each engine every cycle |
| `shruwd_list_entities` · `shruwd_add_competitor` · `shruwd_set_entity` · `shruwd_remove_entity` | The brand and its competitors, with the exact aliases that count |
| `shruwd_run_measurement` · `shruwd_list_cycles` | Measure now; watch the cycle |
| `shruwd_get_visibility` · `shruwd_get_visibility_series` · `shruwd_get_crawlers` | Mention rate and share of voice with intervals, and verified crawler activity |
| `shruwd_list_answers` | The latest individual answers. Evidence, not a metric |
| `shruwd_list_suggestions` · `shruwd_accept_suggestion` · `shruwd_dismiss_suggestion` | Competitors the answers named that you do not track |
| `shruwd_suggest_setup` | Drafts prompts and competitors from your homepage. Nothing is saved |
| `shruwd_list_findings` · `shruwd_get_finding` · `shruwd_transition_finding` | Diagnoses with a specific fix; mark one applied to start the recheck. Capped plans count the rest in `locked` |
| `shruwd_create_ingest_token` | The token and endpoint for shipping server logs. Needs `admin` |

## What the tools will not do

No tool computes anything the API does not return. The server is a transport, and every
guarantee the API keeps, it keeps:

- **A metric is never a bare number.** Each carries its 95% interval and `n`, or an
  explicit `insufficient_data` — which the tool descriptions tell the agent not to read as
  zero.
- **No tool can mark a finding resolved.** `resolved` and `not_moved` belong to the
  recheck. An agent can acknowledge, apply or dismiss; it cannot declare success.
- **Nothing is saved without you.** `shruwd_suggest_setup` drafts prompts and competitors
  and saves none of them — they go in through the normal tools, with the same checks as
  adding them by hand.
- **A capped plan hides nothing silently.** Where your plan shows only its top findings,
  `shruwd_list_findings` returns those and counts the rest in `locked` by severity, so the
  agent is told they exist rather than reporting a short list as the whole set. Fetching a
  locked one is `403 not_entitled`.

## Next steps

- [For AI agents](https://shruwd.io/docs/api/for-ai-agents.md) — the docs themselves, machine-readable
- [TypeScript SDK](https://shruwd.io/docs/api/typescript-sdk.md) — the client underneath these tools