# MCP server

`@splithub/mcp` is a stdio Model Context Protocol server that exposes the `splithub` CLI as tools. Claude Code, Cursor, Codex, Windsurf or any MCP client can create experiments, read verdicts, start, pause, finish and push, using the same config file and credentials as the CLI.

## Register it

`npx splithub init` and `npx splithub skills --mcp` write the entries. By hand:

```json
// .mcp.json (Claude Code, committed) · .cursor/mcp.json (Cursor)
{ "mcpServers": { "splithub": { "command": "npx", "args": ["-y", "@splithub/mcp"] } } }
```

```bash
claude mcp add splithub -- npx -y @splithub/mcp
```

Other clients: command `npx`, args `-y @splithub/mcp`.

Environment: `SPLITHUB_PROJECT_DIR` (defaults to the client's working directory), `SPLITHUB_API` (staging or a self-hosted cloud), `SPLITHUB_API_KEY` (CI), `SPLITHUB_CLI` (path to a specific CLI build).

## Tools

| Tool | Does | Notes |
|---|---|---|
| `splithub_status` | every experiment with status, visitors, days, verdict headline | start here |
| `splithub_results` | full verdict for one experiment | the agent should report `verdict.message` verbatim |
| `splithub_review` | AI reviews stored in the cloud (Pro): at start, on verdict changes or a weekly check, on finish, on demand | an analyst's opinion; the verdict stays the source of truth |
| `splithub_create_experiment` | adds an experiment to `splithub.config.ts` | kind, id, variants, weights, goal, values, match/to, status, description |
| `splithub_set_status` | `running` / `paused` / `finished` | live in cloud mode |
| `splithub_push` / `splithub_pull` | sync the config with the cloud | pull adopts dashboard-created experiments |
| `splithub_doctor` | checks the installation | run after wiring code |
| `splithub_login` | returns a sign-in link and a code | the agent shows it to the user and waits |
| `splithub_whoami` | connected project and public key | |
| `splithub_init` | sets up SplitHub in the project | once per project |

Every tool returns the CLI's `--json` output as text. Errors come back with `isError` and, when the folder is not connected, a hint to call `splithub_login`.

## A typical session

1. User: "A/B test the pricing page headline."
2. Agent calls `splithub_status` (is anything running on that page?), then `splithub_create_experiment` with `kind: value`, two variants, the `signup` goal.
3. Agent edits the component to read `useValue('pricing-title')`, calls `splithub_doctor`.
4. Agent asks the user to confirm, then `splithub_set_status running` and `splithub_push`.
5. Days later: `splithub_results` → "keep running; the estimate is 3,200 visitors per variant in total" or "winner found". The agent ships the winner and calls `splithub_set_status finished`.

The [agent skills](/docs/agent-skills) tell the agent these rules; the MCP tools are what it executes them with.