MCP Tool Reference

Statewright exposes 7 tools via the MCP protocol. These tools are always available regardless of allowed_tools restrictions (workflow control tools are never gated).

statewright_get_state

Get the current state machine state, available tools, transitions, and iteration count.

Return Value

{
  "state": "planning",
  "is_final": false,
  "allowed_tools": ["Read", "Grep", "Glob"],
  "transitions": [
    { "event": "READY", "target": "implementing" },
    { "event": "FAIL", "target": "failed" }
  ],
  "iteration": 3,
  "max_iterations": 10,
  "instructions": "Read and understand the code. Do not modify files.",
  "transition_count": 0,
  "blocked_env": null,
  "env_overrides": null,
  "context": { "test_result": null },
  "guards": {
    "tests_passed": { "field": "test_result", "op": "eq", "value": "pass" }
  }
}

Field	Type	Description
`state`	`string`	Current state name
`is_final`	`boolean`	Whether the current state is terminal
`allowed_tools`	`string[]`	Tools available in the current state
`transitions`	`array`	Available transitions with event names and targets
`iteration`	`integer`	Tool calls made in the current state
`max_iterations`	`integer \| null`	Iteration limit for the current state
`instructions`	`string \| null`	State-specific instructions
`transition_count`	`integer`	Total transitions since workflow was loaded
`blocked_env`	`string[] \| null`	Blocked environment variables
`env_overrides`	`object \| null`	Environment variable overrides
`context`	`object`	Current state machine context
`guards`	`object \| null`	Guard definitions relevant to current transitions

Example

statewright_get_state()

statewright_transition

Transition the state machine to a new state by emitting an event.

Parameters

Parameter	Type	Required	Description
`event`	`string`	Yes	The transition event name (e.g., `DONE`, `FAIL`, `PLAN_READY`)
`data`	`object`	No	Context data to merge into the state machine context. Used for guard evaluation on conditional transitions.

Return Value (Success)

{
  "transitioned": true,
  "from": "planning",
  "to": "implementing",
  "requires_approval": false,
  "transition_count": 1,
  "usage": {
    "transitions": 1,
    "limit": 50,
    "remaining": 49
  }
}

Field	Type	Description
`transitioned`	`boolean`	Always `true` on success
`from`	`string`	Previous state
`to`	`string`	New state
`requires_approval`	`boolean`	Whether human approval is needed before proceeding
`transition_count`	`integer`	Total transitions in this session
`usage.transitions`	`integer`	Transitions used
`usage.limit`	`integer \| null`	Transition limit (null if unlimited)
`usage.remaining`	`integer \| null`	Transitions remaining
`usage.warning`	`string`	Present when approaching the limit

Error Cases

Guard blocked: "Transition 'DEPLOY' from state 'testing' was blocked by a guard condition."
No matching event: "No transition for event 'UNKNOWN' in state 'planning': ..."
Final state: "Cannot transition: state machine is in final state 'completed'."

Examples

Simple transition:

statewright_transition(event="READY")

Transition with context data for guard evaluation:

statewright_transition(
  event="DEPLOY",
  data={"test_result": "pass", "coverage": 92}
)

statewright_load_workflow

Load a named workflow, resetting the state machine to the workflow's initial state.

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Workflow name to load (e.g., `bugfix`, `etl-pipeline`)
`session_id`	`string`	No	Client session identifier for per-session state isolation
`project_id`	`string`	No	Project identifier (cwd hash) for per-project run scoping

Example

statewright_load_workflow(name="bugfix")

With session isolation:

statewright_load_workflow(
  name="deploy-pipeline",
  session_id="abc123",
  project_id="proj_9f8e7d"
)

statewright_list_workflows

List all available named workflows and which one is currently active.

Example

statewright_list_workflows()

Returns the names of all workflows registered with the gateway and indicates which (if any) is currently loaded.

statewright_get_status

Get gateway status: active workflow, current state, available workflows.

Example

statewright_get_status()

Returns a summary combining the active workflow name, current state, and the full list of available workflows. Use this for a quick overview without the full detail of statewright_get_state.

statewright_deactivate

Deactivate workflow enforcement. All tools pass through without restriction.

Example

statewright_deactivate()

After deactivation, tool calls are no longer gated. The agent has unrestricted access to all tools. Use this to exit a workflow early without reaching a final state.

statewright_create_workflow

Create a new workflow from a JSON definition.

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Workflow name (lowercase, hyphens, e.g., `data-pipeline`)
`definition`	`object`	Yes	Full workflow definition matching the schema

Example

statewright_create_workflow(
  name="code-review",
  definition={
    "id": "code-review",
    "initial": "reading",
    "states": {
      "reading": {
        "allowed_tools": ["Read", "Grep", "Glob"],
        "instructions": "Read the PR diff. Identify issues.",
        "max_iterations": 15,
        "on": {
          "DONE": "reporting"
        }
      },
      "reporting": {
        "allowed_tools": ["Read", "Write"],
        "instructions": "Write the review summary.",
        "on": {
          "DONE": "complete"
        }
      },
      "complete": { "type": "final" }
    }
  }
)

The definition must conform to the workflow schema at https://statewright.ai/workflow-schema.json. See the Schema Reference for field documentation.

Tool Call Flow

A typical workflow session follows this sequence:

1. statewright_load_workflow(name="bugfix")
2. statewright_get_state()                        # check initial state
3. [agent works within allowed tools]
4. statewright_transition(event="READY")           # advance to next phase
5. statewright_get_state()                        # check new state
6. [agent works within new allowed tools]
7. statewright_transition(event="DONE")            # advance again
8. [repeat until final state]

The agent calls statewright_get_state to understand what tools are available and what transitions exist. It calls statewright_transition to move forward. The gateway enforces allowed_tools on every other tool call in between.

MCP Tool Reference

On this page