- Explain opt-in configuration, protected surfaces, migrations and cookie behavior. - Document operator CLI, MCP bearer use, cleanup, and supported local origins.
7.4 KiB
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):
{
"url": "https://liqa.example/mcp",
"headers": {
"Authorization": "Bearer <synthetic-token>"
}
}
Keep the token secret and renew it when it expires. See development.md 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), 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
typefield (login,exec,sign) increate_scenario_step,update_scenario_stepandimport_scenariois a legacy field kept for compatibility; it's ignored, and every step runs itsexecCode.