StateSet API Docs

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:

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.

claude mcp add stateset-agents -- stateset-agents mcp

Or as client configuration directly:

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

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.

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.

A loop through the tools

What an agent driving this actually does, in order:

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:

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

Agents quickstart

The same loop from the command line, including the training step MCP will not run.

CLI reference

What each wrapped command does natively.

MCP servers

The other servers StateSet publishes.

Agent Gate

Requiring an authorization proof before any MCP tool call takes effect.

Get started

Platform

StateSet One

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce

StateSet EDI

StateSet Mail

StateSet Voice

StateSet NSR

AI Agents

StateSet Agents

StateSet Sandbox

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Tools

Agents MCP server

Install and run

The tools

A loop through the tools

Verifying it works

Next steps

Agents quickstart

CLI reference

MCP servers

Agent Gate

​Install and run

​The tools

​A loop through the tools

​Verifying it works

​Next steps

Agents quickstart

CLI reference

MCP servers

Agent Gate

Install and run

The tools

A loop through the tools

Verifying it works

Next steps