MCP Tool Catalog

This page documents all 17 tools exposed by the RTILA engine MCP server, organized by category. Each tool’s parameters, defaults, and behavior are described in full.

Source of truth: The complete argument schemas are defined in deno/src/mcp/capabilities.js in the engine repository. This page mirrors that file.

Schema Validation Rules

Two rules apply to every tool call:

Rule	Description
Unknown arguments are rejected	The server validates every request against the declared schema. A typo’d parameter name is an error, not a no-op.
Integer arguments must be JSON integers	"per_page": 50 is correct. "per_page": "50" (a string) fails validation.

---

Browser Tools (Async)

Browser tools spawn a real browser and take minutes to complete. They are asynchronous by default: they return a run_id immediately, and you poll for completion. See MCP Workflows — The Async Contract for the full polling pattern.

Parameters shared by all browser tools:

Parameter	Type	Default	Description
wait	boolean	false	If true, blocks until the run finishes and returns the payload inline. Only use when you know the client’s tool-call deadline covers the work.
timeout_ms	integer	Varies	Maximum wait time in milliseconds. Only meaningful when wait: true.

rtila_analyze_page

Opens a URL in a real browser and produces a structured analysis report including page features, selectors, forms, tables, XHR/fetch network requests, and WAF detection.

Parameter	Type	Required	Default	Description
url	string	✅ Yes	—	Absolute URL to analyze.
settings	object	No	—	Project settings overrides: proxy, captcha, humanoid behavior, timeouts. Same vocabulary as project settings.
browser_profile_config	object	No	—	Browser profile configuration. Same vocabulary as the --browser-profile-config engine flag.
show_instance	boolean	No	false	If true, shows the browser window during analysis.
wait	boolean	No	false	Block until complete.
timeout_ms	integer	No	300000	Timeout in ms. Only with wait: true.
full_response	boolean	No	false	If false, strings over 20,000 characters are truncated.

Typical duration: 90 seconds. Up to 180 seconds with a proxy. Longer if a CAPTCHA is solved.

Example:

{
  "url": "https://example.com/products",
  "settings": {
    "humanoidEnabled": true,
    "proxyEnabled": false
  }
}

rtila_analyze_api_endpoint

Same engine mode as rtila_analyze_page, aimed at an API endpoint. Returns an analysis report for the endpoint’s response in a browser context.

Parameter	Type	Required	Default	Description
url	string	✅ Yes	—	Absolute URL of the API endpoint.
settings	object	No	—	Project settings overrides.
wait	boolean	No	false	Block until complete.
timeout_ms	integer	No	300000	Timeout in ms. Only with wait: true.

⚠️ Important: This tool does not run the engine’s interception pipeline. Automatic pagination detection (parameter/step/total/cursor detection) lives in interception_helpers.js and only executes inside a project run on a project with no commands and no datasets. If you need real pagination detection, run such a project — do not expect it from this tool. See Smart Network API Interception for details.

rtila_run_project

Executes a stored project by its ID.

Parameter	Type	Required	Default	Description
project_id	string	No	Server default	The project to run. Defaults to the server’s configured --project-id.
session_id	string	Conditional	Server default	Required unless the server was launched with --session-id. Needed for checkpointing and log attribution.
variables	object	No	—	Run-scoped variable overrides. Array values are joined by newlines to produce a list. Example: {"SEARCH_TERM": "shoes"}
resume	boolean	No	false	Resume from the stored checkpoint of an interrupted run.
retry_failed	boolean	No	false	Retry only the URLs that failed in the previous run.
browser_profile_id	string	No	—	Persistent browser profile to launch with.
browser_executable_path	string	No	—	Specific browser binary to use.
output_dir	string	No	—	Output directory for standalone output.
wait	boolean	No	false	Block until complete.
timeout_ms	integer	No	1800000	Timeout in ms (30 minutes). Only with wait: true.

⚠️ Do not pass wait: true for project runs unless the user explicitly asks to block. Project runs take minutes, and a client-side timeout cancels the worker mid-run, losing the work.

rtila_run_project_by_name

Resolves an exact project name to an ID, then runs it. Identical to rtila_run_project except it adds a name parameter.

Parameter	Type	Required	Default	Description
name	string	✅ Yes	—	The exact project name to resolve. Fails if more than one project has this name.
(all other parameters)				Same as rtila_run_project.

Tip: If the name is ambiguous, use rtila_list_projects to find the correct ID first, then call rtila_run_project with the ID.

rtila_build_project

Opens the extension/builder mode so a project can be recorded interactively.

Parameter	Type	Required	Default	Description
active_project_id	string	No	—	The project to open in the builder.
browser_profile_config	object	No	—	Browser profile configuration.
extra_args	array	No	—	Raw engine flags appended verbatim.
wait	boolean	No	false	Block until the builder is closed.
timeout_ms	integer	No	1800000	Timeout in ms. Only with wait: true.

⚠️ This mode opens an interactive browser. It is for a human to drive — it is not a headless “generate a project” button. See Recording for how the builder works.

---

Run Control Tools (Sync)

Run control tools manage the lifecycle of runs started by this server session.

rtila_get_run_status

Returns the status of a run started by this server.

Parameter	Type	Required	Description
run_id	string	✅ Yes	The run ID returned by a browser tool.

Response fields:

Field	Type	Description
run_id	string	The run identifier.
label	string	Human-readable description of the run.
status	string	running, succeeded, or failed.
exit_code	integer	Process exit code (0 = success).
pid	integer	Process ID of the worker.
started_at	string	ISO timestamp of when the run started.
ended_at	string	ISO timestamp of when the run ended (null if still running).
error	string	Error message if the run failed.
meta	object	Additional metadata about the run.
stderr_tail	string	Present when status is failed. Contains the engine’s error classification. Read this before guessing at the cause.

rtila_get_run_result

Returns the parsed JSON envelope of a finished run.

Parameter	Type	Required	Default	Description
run_id	string	✅ Yes	—	The run ID.
full_response	boolean	No	false	If false, long strings are truncated.

Response fields:

Field	Type	Description
result	object or null	The parsed JSON envelope. null for project runs (their output is rows in the database, not a payload).
result_available	boolean	Whether a result envelope was produced.
stderr_tail	string	Stderr output if the run failed.
stdout_truncated	boolean	Whether stdout was truncated.

Important: result: null for project runs is expected behavior, not an error. A project run’s outcome is its status; its output is rows in the database, readable via rtila_get_project_data.

rtila_get_run_log

Returns the captured stdout/stderr tails of a run.

Parameter	Type	Required	Default	Description
run_id	string	✅ Yes	—	The run ID.
tail_chars	integer	No	8000	Number of characters to return from the end of each stream.

rtila_cancel_run

Stops a running engine subprocess.

Parameter	Type	Required	Default	Description
run_id	string	✅ Yes	—	The run ID to cancel.
force	boolean	No	false	If true, skips the graceful shutdown signal and terminates immediately.

Waits up to 5 seconds for the process to exit and returns the final status.

Note: A client timeout on a wait: true call cancels the worker automatically. You only need rtila_cancel_run for explicit cancellation.

rtila_list_runs

Lists every run this server has started in this session. No arguments.

Retention: Only the 50 most recent finished runs are retained. Run records live in the server process and do not survive a server restart. Poll promptly.

---

Data Tools (Sync, Read-Only)

Data tools read directly from the local PocketBase database. They are fast, synchronous, and require --rest-api to be configured.

rtila_list_projects

Lists project records from the database.

Parameter	Type	Required	Default	Description
filter	string	No	—	PocketBase filter expression. Example: name~"scrape"
sort	string	No	-updated	Sort field. Prefix with - for descending.
page	integer	No	1	Page number.
per_page	integer	No	50	Results per page. Maximum: 200.

rtila_get_project

Retrieves a single project record.

Parameter	Type	Required	Description
project_id	string	✅ Yes	The project ID.

rtila_get_project_config

Returns a project’s parsed content JSON (settings, commands, datasets).

Parameter	Type	Required	Default	Description
project_id	string	✅ Yes	—	The project ID.
summary_only	boolean	No	false	If true, returns counts and names only instead of the full content JSON.

rtila_list_datasets

Lists a project’s datasets and their properties.

Parameter	Type	Required	Description
project_id	string	✅ Yes	The project ID.

Response includes for each dataset: name, parent, item_selector, and properties (each with key, name, type, selector, transformations).

rtila_get_project_data

Reads scraped rows from a project’s dataset collection.

Parameter	Type	Required	Default	Description
dataset	string	✅ Yes	—	The dataset name. Example: "Auto_Intercepted_Data", "products".
project_id	string	No	Server default	The project ID. Defaults to the configured project.
filter	string	No	—	PocketBase filter expression.
sort	string	No	-created	Sort field.
page	integer	No	1	Page number.
per_page	integer	No	50	Results per page. Maximum: 200.

Collection naming: The underlying PocketBase collection is named <project_id>_<dataset_name> with every non-alphanumeric character in the dataset name replaced by _. This is the same mapping the engine uses when writing rows.

rtila_get_logs

Reads log records from the database.

Parameter	Type	Required	Default	Description
session_id	string	No	Server default	Filter by session. Defaults to the configured session.
level	string	No	—	Filter by log level. Example: "WARN", "ERROR", "CRITICAL".
page	integer	No	1	Page number.
per_page	integer	No	50	Results per page. Maximum: 200.

rtila_engine_info

Returns server configuration and status. No arguments.

Response includes: version, engine command, configured database URL, default project ID, default session ID, whether a token is set, and the number of active runs.

Tip: Call rtila_engine_info first when something behaves unexpectedly. It tells you exactly what the server was launched with.

---

Resources

Read-only resources for MCP clients that support the resources protocol:

Resource URI	Description
rtila://projects	List of all projects
rtila://projects/{projectId}	A single project record
rtila://projects/{projectId}/config	A project’s parsed configuration
rtila://projects/{projectId}/datasets	A project’s dataset definitions
rtila://projects/{projectId}/data/{dataset}	Scraped rows from a specific dataset
rtila://runs	All runs in this session
rtila://runs/{runId}	A specific run record
rtila://engine/info	Engine version and configuration

---

Prompts

Built-in prompt templates for clients that support the prompts protocol:

Prompt Name	Arguments	Description
rtila_build_scraper	url (required), goal	Guides the AI through analyzing a page and building an extraction plan.
rtila_optimize_selector	selector (required), page_summary	Helps optimize a CSS/XPath selector for reliability.
rtila_explain_dataset	dataset (required), project_id	Explains a dataset’s structure, properties, and transformations.

---

Tool Selection Guide

What you want to do	Tool to use
Analyze a web page’s structure	rtila_analyze_page
Analyze an API endpoint	rtila_analyze_api_endpoint
Run a project by ID	rtila_run_project
Run a project by name	rtila_run_project_by_name
Open the interactive builder	rtila_build_project
Check if a run finished	rtila_get_run_status
Get analysis results	rtila_get_run_result
Stop a running task	rtila_cancel_run
See all runs this session	rtila_list_runs
List all projects	rtila_list_projects
Read a project’s configuration	rtila_get_project_config
See what datasets a project defines	rtila_list_datasets
Read scraped data	rtila_get_project_data
Read execution logs	rtila_get_logs
Check server configuration	rtila_engine_info