Files
liqa/docs/mcp.md
T
agent 9bdba32a34 docs(auth): document optional authentication setup
- Explain opt-in configuration, protected surfaces, migrations and cookie behavior.
- Document operator CLI, MCP bearer use, cleanup, and supported local origins.
2026-11-09 15:50:12 -05:00

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 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.