# Wake MCP

> Connect your coding assistant to your desk. Wake is an MCP server (Model Context Protocol, streamable HTTP, JSON responses) at `POST /api/wake/v1/mcp`, authenticated with the same bearer key as the API.

Your assistant gets one tool per question the desk can answer:

| Tool | Answers |
|---|---|
| `wake_me` | Which site this key reads, verification and collector status. |
| `wake_overview` | Headline numbers, funnel and top friction for a window. |
| `wake_agents` | Who came: one row per nickname. |
| `wake_sessions` | Session rows; filter by nickname, limit up to 500. |
| `wake_funnel` | Stages, shares, biggest drop. |
| `wake_friction` | Where agents got stuck and the fixes implied. |
| `wake_fixes` | Ranked fixes with evidence plus readiness recommendations. |
| `wake_pages` | Page classes and common sequences. |
| `wake_alerts` | What changed versus the previous window. |
| `wake_series` | Time buckets. |
| `wake_readiness` | The public site as an agent sees it, with publish-ready files. |
| `wake_listing` | The AEO plan, step status, arrivals, trial. |
| `wake_benchmarks` | Cohort medians (k-anonymous). |
| `wake_install` | Collector status; `kit: true` returns the deploy-ready files. |
| `wake_listing_plan` | Prepares the listing plan (never publishes). |

All tools take `window` (`24h`, `7d`, `30d`) where it applies. Replace `<key>` with a key minted under **Connect your AI** and `<origin>` with your desk origin (for the hosted desk: `https://agent-observatory-desk-production.up.railway.app`).

## Claude Code

```bash
claude mcp add --transport http wake <origin>/api/wake/v1/mcp --header "Authorization: Bearer <key>"
```

Then ask: *"Use wake_fixes to tell me what to change on my site this week."*

## Cursor

Save as `.cursor/mcp.json` in your project (or in `~/.cursor/mcp.json` for every project):

```json
{ "mcpServers": { "wake": { "url": "<origin>/api/wake/v1/mcp", "headers": { "Authorization": "Bearer <key>" } } } }
```

## Codex

In `~/.codex/config.toml`:

```toml
[mcp_servers.wake]
url = "<origin>/api/wake/v1/mcp"
bearer_token_env_var = "WAKE_API_KEY"
```

and `export WAKE_API_KEY=<key>` in the shell that starts Codex.

## Claude Desktop and other stdio-only clients

Use the CLI as a bridge:

```json
{ "mcpServers": { "wake": { "command": "npx", "args": ["-y", "wake-agents", "mcp"], "env": { "WAKE_API_KEY": "<key>", "WAKE_API_URL": "<origin>" } } } }
```

## ChatGPT

ChatGPT connectors need an OAuth-fronted MCP server; Wake uses API keys today. Use the [API](/wake/docs/api) from a custom GPT action with the bearer header, or the CLI.

## Protocol notes

- JSON-RPC 2.0 over POST; the server answers `application/json`. `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list` and `prompts/list` are implemented; notifications get HTTP 202. There is no server-initiated event stream (GET returns 405), and no session id is required.
- Protocol versions `2025-06-18`, `2025-03-26` and `2024-11-05` are accepted.
- Tool results carry the JSON both as `content[0].text` and as `structuredContent`.
- Every tool is read-only except `wake_listing_plan`, which writes a plan to your own desk and publishes nothing.