MCP Interface Documentation

March 8, 2026 · View on GitHub

OpenTester exposes core project/case/template/execution operations through MCP.

Connection Information

OpenTester currently runs the MCP server with streamable-http transport.

Endpoint: http://localhost:8001/mcp
Transport: Streamable HTTP
Behavior: request/response over HTTP; may use streaming patterns depending on client/server support

STDIO transport is not enabled in the current implementation. The MCP server only supports Streamable HTTP transport at this time.

Future versions may add STDIO support for local process-based clients.

For local clients that launch a process (for example Claude Desktop), use stdio server config:

{
  "mcpServers": {
    "opentester": {
      "command": "opentester",
      "args": ["mcp"]
    }
  }
}

Add MCP configuration in .claude/settings.json:

{
  "mcpServers": {
    "opentester": {
      "url": "http://localhost:8001/mcp"
    }
  }
}

Tool names below follow the current FastMCP function names from backend/opentester/mcp/server.py.

Tool	Parameters	Description
`validate_dsl`	`dsl_yaml`	Validate DSL YAML and schema
`save_case`	`project_id`, `name`, `dsl_yaml`, `case_id` (optional)	Create or update a case
`delete_case`	`project_id`, `case_id`	Delete a case

Tool	Parameters	Description
`run_case`	`project_id`, `case_id`	Start single-case execution via FastAPI bridge
`run_project`	`project_id`, `case_ids` (optional)	Start executions for project cases
`stop_execution`	`execution_id`	Stop a running execution
`get_execution_status`	`execution_id`	Fetch execution status
`get_execution_log`	`execution_id`	Fetch detailed results

Tool	Parameters	Description
`request_dom_analysis`	`execution_id`	Fetch DOM snapshot and context when execution is paused for AI
`submit_ai_selector`	`execution_id`, `selector`, `selector_type` (optional), `reasoning` (optional)	Submit selector and resume paused execution
`list_paused_executions`	-	List all executions waiting for AI selector input

Tool	Parameters	Description
`list_templates`	`category` (optional), `target_type` (optional), `tag` (optional)	List templates
`get_template`	`template_id`	Get template details
`create_template`	`name`, `dsl_template`, `description` (optional), `target_type` (optional), `category` (optional), `tags` (optional)	Create template
`update_template`	`template_id`, mutable fields	Update template
`delete_template`	`template_id`	Delete template
`instantiate_template`	`template_id`, `project_id`, `case_name`, `variables` (optional)	Create case from template
`create_template_from_case`	`project_id`, `case_id`, `template_name`, `description` (optional), `category` (optional), `variable_mappings` (optional)	Convert case to template

run_case, run_project, stop_execution, get_execution_status, and get_execution_log call FastAPI endpoints (for example /api/execution/run) so execution state is tracked in the shared execution manager.
request_dom_analysis, submit_ai_selector, and list_paused_executions operate directly through the execution manager/shared execution state, not via FastAPI HTTP bridge.
If FastAPI is not reachable, the FastAPI-bridged execution tools fail even if the MCP server itself is running.
Web executor supports ai_locator flow: execution may enter paused_waiting_for_ai, then resume after submit_ai_selector.