MCP Server

The RTILA engine binary (rtila-engine) doubles as a Model Context Protocol (MCP) server. There is no second binary, no separate installation, and no additional download: the same executable that runs your automation projects exposes RTILA’s browser automation, page analysis, project execution, and data access to any MCP-compatible client when started with the --mcp flag.

This means you can connect Claude Code, Claude Desktop, Cursor, VS Code with GitHub Copilot, Windsurf, Continue.dev, Cline, or any other stdio-based MCP client directly to your RTILA installation and drive the full automation engine through natural language.

New in v8.3.2: The engine-based MCP server replaces the previous desktop-app-embedded MCP tools. The AI Assistant’s internal analysis tools (analyze_target_page, navigate_and_analyze, request_user_input) remain available within the RTILA X desktop application, but the engine MCP server is a separate, more powerful interface designed for external AI clients. See AI Assistant Overview for the built-in tools.

MCP Server architecture showing rtila-engine in MCP mode connecting to external AI clients via stdio

What the MCP Server Does

The MCP server exposes 17 tools organized into three categories:

Category	Tools	Transport	Description
Browser Tools	5	Async (spawn a real browser)	Analyze pages, run projects, open the builder
Run Control	5	Sync	Poll status, get results, cancel, list runs
Data Tools	7	Sync (direct database reads)	List projects, read configs, query scraped data, read logs

The server also exposes read-only resources (project listings, run records, engine info) and built-in prompts (build scraper, optimize selector, explain dataset) for clients that support them.

How It Works

┌──────────────────────────────────────────────────────┐
│              Your MCP Client                         │
│   (Claude Code, Cursor, VS Code, Windsurf, etc.)    │
└──────────────┬───────────────────────────────────────┘
               │  stdio (newline-delimited JSON-RPC 2.0)
               ▼
┌──────────────────────────────────────────────────────┐
│         rtila-engine --mcp  (coordinator)            │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │ Browser     │  │ Run Control │  │ Data Tools  │  │
│  │ Tools       │  │ Tools       │  │ (DB reads)  │  │
│  │ (spawn      │  │ (poll,      │  │             │  │
│  │  workers)   │  │  cancel)    │  │             │  │
│  └──────┬──────┘  └─────────────┘  └──────┬──────┘  │
│         │                                   │         │
└─────────┼───────────────────────────────────┼─────────┘
          │                                   │
          ▼                                   ▼
   ┌─────────────┐                   ┌─────────────┐
   │ Browser     │                   │ PocketBase  │
   │ Workers     │                   │ Database    │
   │ (Playwright)│                   │ (REST API)  │
   └─────────────┘                   └─────────────┘

Browser work spawns the engine itself in the matching worker mode — the same invocation the desktop app uses.
Data reads go straight to the local PocketBase database via its REST API.
Nothing about normal project runs changes. The MCP server is an additional interface, not a replacement.

Prerequisites

Requirement	Details
RTILA X installed	Provides the `rtila-engine` binary. Alternatively, a `deno/` source checkout works.
Local database running	The PocketBase database must be reachable at the URL you pass as `--rest-api`. RTILA’s PocketBase defaults to `http://127.0.0.1:8090` — confirm the port with your installation. The desktop app uses port `8880` by default.
An MCP client	Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Continue.dev, Cline, or any stdio-compatible client.

Important: The RTILA X desktop application does not need to be open. However, the local database process must be running and reachable. If you installed RTILA X via the desktop app, the database starts automatically when the app launches. For standalone engine use, ensure the database is running before connecting.

Tip: To confirm your database port, check Preferences → General in the RTILA X desktop app, or look at the database startup log. The default desktop app port is 8880; the standalone engine default is 8090.

Finding the Engine Binary

The engine ships as a Tauri sidecar alongside the RTILA X application. Locate it once and use the absolute path in all client configurations.

macOS

The engine is inside the application bundle:

ls /Applications/RTILA.app/Contents/MacOS/ | grep rtila-engine
# → rtila-engine

The full path is:

/Applications/RTILA.app/Contents/MacOS/rtila-engine

Windows (PowerShell)

Search the common installation directories:

Get-ChildItem "$env:LOCALAPPDATA\RTILA","$env:ProgramFiles\RTILA" `
  -Filter "rtila-engine*.exe" -Recurse -ErrorAction SilentlyContinue |
  Select-Object -ExpandProperty FullName

Common locations:

Location	Path
Per-user install	`%LOCALAPPDATA%\RTILA\rtila-engine.exe`
System-wide install	`%ProgramFiles%\RTILA\rtila-engine.exe`

Important: On Windows, always use the full path with .exe extension. When configuring JSON files, every backslash in the path must be escaped (doubled): C:\\Users\\you\\AppData\\Local\\RTILA\\rtila-engine.exe.

Linux

If installed via .deb:

dpkg -L rtila | grep rtila-engine

If installed via .AppImage, the engine is bundled inside the AppImage. Extract it or use the source checkout method below.

Common locations:

Location	Path
deb install	`/opt/RTILA/rtila-engine` or `/usr/lib/rtila/rtila-engine`
AppImage	Bundled internally (extract with `--appimage-extract`)

From a Source Checkout (Deno)

If you have the RTILA source code with the deno/ directory, you can run the engine through Deno directly — no compiled binary needed:

deno run -A /absolute/path/to/deno/index.js --mcp --rest-api http://127.0.0.1:8090 --session-id my-session

Substitute this command everywhere the documentation shows rtila-engine.

Note: Workers spawned by the coordinator are launched with full permissions (deno run -A in a source checkout), so no extra permission flags are needed.

Quick Start

The minimum viable configuration requires the database URL and a session ID:

rtila-engine --mcp --rest-api http://127.0.0.1:8090 --session-id mcp-session

This launches a long-running stdio server. You normally never run it by hand — your MCP client spawns it automatically. But running it once is the best way to confirm it starts correctly:

# Expect: [MCP] server started {...} on stderr, then it waits on stdin.
# Press Ctrl-C to stop.
rtila-engine --mcp --rest-api http://127.0.0.1:8090 --session-id smoke

If you see [MCP] server started on stderr, the server is working. If you see an error, check:

Error	Fix
`command not found` / `not recognized`	The path to `rtila-engine` is wrong. Re-check with the platform instructions above.
`address already in use`	Another process is using the database port. Close it or use a different port.
`database is not configured`	You omitted `--rest-api`. Add it.

What Works Without `--rest-api`

Only the two analysis tools work without a database connection:

Tool	Works without DB?
`rtila_analyze_page`	✅ Yes
`rtila_analyze_api_endpoint`	✅ Yes
All data tools	❌ No — requires `--rest-api`
All project run tools	❌ No — requires `--rest-api`

Launch Flags Reference

Every flag has an environment-variable fallback, so the same configuration can be shared across clients without putting secrets on the command line.

Flag	Environment Variable	Required	Purpose
`--mcp`	—	Yes	Selects MCP server mode. Without this flag, the engine runs in its normal project-execution mode.
`--rest-api <url>`	`RTILA_API_URL`	For data tools and project runs	Base URL of the local PocketBase database API. Example: `http://127.0.0.1:8090`
`--rest-api-token <token>`	`RTILA_TOKEN`	Recommended	Authentication token, sent raw as the `Authorization` header. Do not prefix with `Bearer` .
`--project-id <id>`	`RTILA_PROJECT_ID`	Optional	Default project ID for tools that accept a `project_id` parameter.
`--session-id <id>`	`RTILA_SESSION_ID`	For project runs	Default session ID for checkpointing and log attribution.
`--verbose`	—	Optional	Extra coordinator diagnostics on stderr. Useful for debugging.

Important Notes

--rest-api, --rest-api-token, --project-id, and --session-id are scanned directly by the coordinator and are never forwarded to workers.
--rest-api <url> requires a session ID for project runs. Either pass --session-id at launch or include session_id on each rtila_run_project call.
The --rest-api-token value is sent raw as the Authorization header. Do not add Bearer prefix — the engine handles the header format internally.

Environment Variable Example

Instead of passing the token on the command line (visible in process lists), use an environment variable:

macOS / Linux:

export RTILA_TOKEN="your-token-here"
rtila-engine --mcp --rest-api http://127.0.0.1:8090 --session-id my-session

Windows (PowerShell):

$env:RTILA_TOKEN = "your-token-here"
& "C:\Users\you\AppData\Local\RTILA\rtila-engine.exe" --mcp --rest-api http://127.0.0.1:8090 --session-id my-session

Windows (CMD):

set RTILA_TOKEN=your-token-here
"C:\Users\you\AppData\Local\RTILA\rtila-engine.exe" --mcp --rest-api http://127.0.0.1:8090 --session-id my-session

Verifying the Installation

The engine ships a smoke-test client that speaks the real MCP protocol:

cd deno
deno run -A tools/mcp_smoke.js --call rtila_engine_info

This performs the initialize handshake, lists tools, calls one, and prints impure stdout lines: 0 on success. That last number is the protocol-purity check — anything above zero means something is writing to stdout that shouldn’t be.

To exercise a browser tool end to end (remember the async default):

deno run -A tools/mcp_smoke.js --call rtila_analyze_page \
  --arguments '{"url":"https://example.com","wait":true}'

Where to Go Next

Topic	Page
Configure your MCP client (Claude Code, Cursor, VS Code, etc.)	MCP Client Setup
Complete tool reference with all parameters	MCP Tool Catalog
Async patterns, workflows, troubleshooting, security	MCP Workflows & Troubleshooting