# 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](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](scenario.md)) | | `import_yaml` | Import any mix of environments, credentials, snippets and scenarios from YAML (see "Import" in [scenario.md](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`.