> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents MCP server

> Drive the grade → curate → retrain loop from Claude Code or your own agent, with no tool that can start a real training run.

`stateset-agents mcp` exposes the improvement loop as MCP tools, so an agent can
run it directly instead of shelling out to the CLI. Every tool is a thin wrapper
over the same module functions the CLI calls — grading, curation and preset
resolution are not reimplemented in the server, so output is comparable either
way.

## Install and run

The server is an optional extra rather than a core dependency:

```bash theme={null}
pip install "stateset-agents[mcp]"
stateset-agents mcp --transport stdio
```

Without the extra, the command exits with the install hint rather than a
traceback. `stdio` is the only transport in v1.

```bash theme={null}
claude mcp add stateset-agents -- stateset-agents mcp
```

Or as client configuration directly:

```json theme={null}
{
  "mcpServers": {
    "stateset-agents": {
      "command": "stateset-agents",
      "args": ["mcp", "--transport", "stdio"]
    }
  }
}
```

## The tools

| Tool                                                                  | Does                                                                                 |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `list_rewards()`                                                      | The rule-based reward names: `gsm8k`, `customer_support`, `tool_calling`, `nsr`      |
| `ingest_transcripts(input_path, format, output_dir)`                  | Convert OpenAI or LangChain logs into per-conversation transcripts                   |
| `grade_transcript(history_path, reward)`                              | Score one transcript — mean plus a per-component breakdown                           |
| `improve_run(transcripts_dir, reward, output_dir, threshold, format)` | Grade a directory, curate above the threshold, write the summary and next steps      |
| `improve_status(output_dir)`                                          | Read back the summary from a previous run                                            |
| `list_model_presets()`                                                | Preset names with their model id, learning rate, lengths and LoRA/quantization flags |
| `dry_run_finetune(model_preset)`                                      | Resolve a preset's agent, reward and trainer config without downloading weights      |

<Warning>
  **No tool in v1 starts real training.** `dry_run_finetune` only ever runs the
  fine-tune script with `--dry-run` against the stub backend: no model download,
  no GPU, no spend. That is a deliberate boundary — an agent driving this loop
  can grade, curate and preview a configuration, and cannot commit you to a
  training bill. Real runs go through the CLI.
</Warning>

<Note>
  `improve_run` calls the same orchestration function as `stateset-agents
      improve run`, so a curated set produced through MCP is byte-for-byte
  comparable with one produced from the shell. That matters when an agent
  curates a set and a person needs to check it.
</Note>

## A loop through the tools

What an agent driving this actually does, in order:

```text theme={null}
list_rewards()                    → pick customer_support
ingest_transcripts(               → transcripts/, 412 conversations
    "logs.jsonl", "openai", "transcripts/")
grade_transcript(                 → mean 0.61, tone 0.8, resolution 0.44
    "transcripts/conv_001.jsonl", "customer_support")
improve_run(                      → curated.jsonl (118 turns kept of 1,340)
    "transcripts/", "customer_support",
    "improved/", threshold=0.7)
improve_status("improved/")       → read the summary back
list_model_presets()              → pick qwen3-8-27b
dry_run_finetune("qwen3-8-27b")   → resolved config, nothing downloaded
```

The agent stops there. Turning that resolved config into a trained model is a
CLI step a person runs, because it is the step that costs money.

## Verifying it works

A `tools/call` against a server with no `mcp` extra, or a bad path, returns a
clear error rather than a traceback — so a failed call tells you which of the
two it was:

```bash theme={null}
stateset-agents mcp --transport stdio <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"tools/list"}
EOF
```

Seven tools in the response means the server is registered and reachable.

## Next steps

<CardGroup cols={2}>
  <Card title="Agents quickstart" icon="rocket" href="/stateset-agents/quickstart">
    The same loop from the command line, including the training step MCP will not run.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/stateset-agents/cli">
    What each wrapped command does natively.
  </Card>

  <Card title="MCP servers" icon="server" href="/mcp-servers">
    The other servers StateSet publishes.
  </Card>

  <Card title="Agent Gate" icon="shield-halved" href="/stateset-nsr-agent-gate">
    Requiring an authorization proof before any MCP tool call takes effect.
  </Card>
</CardGroup>