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 preset builders in-process: no model download, GPU, or training launch. For actual execution, an authorized agent can separately use the fine-tuning JSON CLI to prepare a private snapshot and launch an exact reviewed plan. MCP tool access does not grant that authority.

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 MCP workflow stops at preview. Continue through a separately authorized CLI launch or hand the prepared run to a person in the terminal studio. Both use the same retained run/checksum rather than rebuilding the request after a disconnect.

Verifying it works

Use an MCP client to complete initialization and call tools/list, then read list_rewards or list_model_presets. A visible catalog proves discovery, not successful curation or training. Inspect returned artifacts and controlled errors from the actual tool. The reviewed source registers seven tools; discover the deployed catalog instead of treating that count as a capability guarantee. This source check was performed October 20, 2026 against stateset_agents/mcp_server.py.

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.

Last modified on October 20, 2026

Get started

Build your first integration

Operate and improve

Resources and support

Platform

Using the APIs

StateSet Response

StateSet ResponseCX

Temporal Engine

StateSet iCommerce Engine

StateSet Warehouse (WMS)

StateSet Freight (TMS)

StateSet EDI

StateSet Mail

StateSet iCommerce Voice Engine

StateSet iCommerce NSR Engine

AI Agents

StateSet Agents

StateSet Sandbox

StateSet ACP

StateSet UCP

StateSet ICP

StateSet Sequencer

StateSet Set L2

StateSet Cloud

Apps & Consoles

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