MCP tools
The MCP endpoint is exposed at /mcp (Streamable HTTP transport), e.g. http://localhost:13000/mcp with the compose setup. Each request is served by a fresh MCP server, so there is no MCP session state between calls.
The server registers the following tools. All entity IDs are UUIDs; list tools are paginated (page, limit, and where noted orderBy / orderDir). Errors are returned as MCP tool errors (isError: true) with the message as text.
Sessions
| Tool |
Description |
list_sessions |
List saved browser sessions (orderBy/orderDir) |
delete_session |
Delete a session by id |
Environments
| Tool |
Description |
list_environments |
List environments (orderBy/orderDir) |
get_environment |
Get one environment by id |
create_environment |
Create an environment: name, optional description, data |
update_environment |
Update name, description and/or data of environment id |
delete_environment |
Delete an environment by id |
data is a free-form map of string keys to string values, read in step code with context.getEnv(key).
Credentials
| Tool |
Description |
list_credentials |
List credentials (orderBy/orderDir). Returns the full data, secrets included |
get_credential |
Get one credential by id (full data) |
create_credential |
Create a credential: name, optional data (JSON-encoded string) |
update_credential |
Update name and/or data; omitted fields are left unchanged |
delete_credential |
Delete a credential; also removes it from scenarios it's assigned to |
Browser (ad-hoc)
| Tool |
Description |
open_url |
Open url, optionally in saved session sessionName; returns title and content (readerMode for readable text, selector to limit to one element) |
exec_code |
Run Playwright JS that receives a single context argument (see scenario.md), optionally after opening url and/or in session sessionName. environmentId loads an environment for context.getEnv(); credentials ({ alias: credentialId }) loads credentials for context.getCredential(alias) |
Scenarios
| Tool |
Description |
list_scenarios |
List scenarios (orderBy/orderDir) |
get_scenario |
Get a scenario (latest version) with its steps |
create_scenario |
Create a scenario: name, optional description, environmentId (default environment), timeoutSeconds |
update_scenario |
Update scenario fields; bumps the version when content changes |
delete_scenario |
Delete a scenario with its steps, versions and runs |
create_scenario_step |
Append a step: execCode, optional title and timeoutSeconds. The schema also requires order and type, but both are ignored: new steps always go last (use update_scenario_step with order to move one) |
get_scenario_step |
Get one step |
update_scenario_step |
Update step fields (including order to move it) |
delete_scenario_step |
Delete a step |
list_scenario_versions |
List a scenario's versions, newest first |
get_scenario_version |
Get one scenario version with its steps |
list_scenario_credentials |
List credentials assigned to a scenario (alias → credential) |
add_scenario_credential |
Assign credential credentialId to a scenario under alias |
remove_scenario_credential |
Remove an assignment by scenarioCredentialId (the assignment id, not the credential id) |
export_scenario |
Export one scenario version (optional version, defaults to the latest) |
import_scenario |
Import one scenario version; version is required (see "Versioning" in scenario.md) |
import_yaml |
Import any mix of environments, credentials, snippets and scenarios from YAML (see "Import" in scenario.md) |
export_e2e_test |
Export one scenario version as a standalone Playwright test project (zip, base64; optional version, defaults to the latest) |
Changes to scenario content (fields and steps) create a new scenario version; credential assignments and files are not versioned.
Runs
| Tool |
Description |
run_scenario |
Start a run of scenario id in environmentId; optional version (defaults to the latest), saveSession, traceMode (on, retain-on-failure, off; defaults to PLAYWRIGHT_TRACE_MODE) |
list_scenario_runs |
List runs of a scenario, optionally filtered by status |
list_all_runs |
List runs across all scenarios, optionally filtered by status |
get_scenario_run |
Get a run with its step runs (outputs) and logs |
wait_for_scenario_run |
Wait until a run is pass or fail (up to 5 minutes), then return it |
Snippets
| Tool |
Description |
list_snippets |
List snippets (orderBy/orderDir) |
get_snippet |
Get one snippet (latest version) |
create_snippet |
Create a snippet: alias, title, code, optional description |
update_snippet |
Update snippet fields; bumps its version when content changes |
delete_snippet |
Delete a snippet and all its versions |
list_snippet_versions |
List a snippet's versions, newest first |
get_snippet_version |
Get one snippet version |
Step code runs a snippet with context.runSnippet("alias", ...args) (latest version) or context.runSnippet("alias@3", ...args) (version 3).
Scenario files
| Tool |
Description |
upload_scenario_file |
Upload a file to a scenario: name, base64 contentBase64, optional mimeType and expiresAt (ISO 8601) |
list_scenario_files |
List a scenario's files (limit, offset) |
get_scenario_file_content |
Get a file's content as base64, with metadata |
Run files
| Tool |
Description |
list_run_files |
List files created during a run (limit, offset): downloads, failure screenshots/HTML, trace.zip |
get_run_file_content |
Get a run file's content as base64, with metadata |
delete_run_file |
Delete a file from a run; the stored file is removed once no scenario or run references it (also DELETE /api/v1/scenarios/:id/runs/:runId/files/:fileId and the delete button on the run detail page) |
Binary content handling
File tools carry binary content as base64 strings in a contentBase64 field, with encoding: "base64" in the response. Decode it to get the original bytes.
Content for upload_scenario_file must be base64-encoded. Run files are only created by runs themselves (context.downloadFile(), failure page dumps, traces) and can't be uploaded.
Notes
- The step
type field (login, exec, sign) in create_scenario_step, update_scenario_step and import_scenario is a legacy field kept for compatibility; it's ignored, and every step runs its execCode.