MCP Server

Roleplay can run as a local MCP stdio server so coding agents can discover scenarios, run scenarios, and inspect local reports.

Start The Server

roleplay mcp

Print metadata and exit:

roleplay mcp --json

Protocol

The server uses MCP protocol version:

2024-11-05

Tools

list_scenarios

List local YAML scenarios.

Input:

{
  "root": ".roleplay/scenarios"
}

root is optional and defaults to .roleplay/scenarios.

list_runs

List local run IDs, newest first.

Input:

{
  "runsDir": ".roleplay/runs"
}

runsDir is optional and defaults to .roleplay/runs.

get_latest_report

Read the latest local JSON report.

Input:

{
  "runsDir": ".roleplay/runs"
}

runsDir is optional and defaults to .roleplay/runs.

run_scenario

Run one scenario and return its report summary.

Input:

{
  "scenario": ".roleplay/scenarios/install-smoke.yml",
  "maxTurns": 8,
  "out": ".roleplay/runs",
  "yes": false
}

Required:

• scenario

Optional:

• maxTurns
• out
• yes

Security Note

The MCP server can run local scenarios and, when yes is true, scenarios may execute CLI target commands. Only connect trusted coding agents to the local MCP server.