# 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. Authentication is disabled by default. When `AUTH_ENABLED=true`, MCP requests must include a valid bearer token from the operator CLI (`user:token`); browser cookies are accepted by the HTTP API, but MCP clients should use the bearer header. For an MCP client that supports custom HTTP headers, configure the endpoint and header like this (replace the synthetic token with a privately issued token): ```json { "url": "https://liqa.example/mcp", "headers": { "Authorization": "Bearer " } } ``` Keep the token secret and renew it when it expires. See [development.md](development.md#operator-account-commands) for provisioning and token issuance. With auth disabled, omit the authorization header. 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`.