MCP Client Setup

This page provides step-by-step configuration instructions for connecting popular MCP clients to the RTILA engine’s MCP server. The engine command is the same in every client — only the configuration file format differs.

Before you start: Make sure you have located the rtila-engine binary on your system. See MCP Server — Finding the Engine Binary for platform-specific instructions.

MCP client configuration flow showing the engine binary path, flags, and environment variables

Configuration Overview

Every client configuration needs three things:

Element	Description	Example
command	Absolute path to the `rtila-engine` binary	`/Applications/RTILA.app/Contents/MacOS/rtila-engine`
args	`--mcp` followed by launch flags	`["--mcp", "--rest-api", "http://127.0.0.1:8090", "--session-id", "cursor"]`
env	Environment variables (recommended for secrets)	`{"RTILA_TOKEN": "your-token"}`

Security: Never put your RTILA_TOKEN in the args array where it would be visible in process listings. Always use the env block or the RTILA_TOKEN environment variable.

Claude Code

Claude Code is Anthropic’s CLI-based AI coding assistant. It supports MCP servers natively.

Option A: CLI Command (Recommended)

Add the RTILA MCP server with a single command:

claude mcp add rtila --scope user \
  -- "/Applications/RTILA.app/Contents/MacOS/rtila-engine" \
  --mcp --rest-api http://127.0.0.1:8090 --session-id claude-code

Windows (PowerShell):

claude mcp add rtila --scope user `
  -- "C:\Users\you\AppData\Local\RTILA\rtila-engine.exe" `
  --mcp --rest-api http://127.0.0.1:8090 --session-id claude-code

To add the token as an environment variable (recommended over command-line args):

claude mcp add rtila --scope user \
  -e RTILA_TOKEN=your-token-here \
  -- "/Applications/RTILA.app/Contents/MacOS/rtila-engine" \
  --mcp --rest-api http://127.0.0.1:8090 --session-id claude-code

Option B: Team-Shared Configuration (`.mcp.json`)

Commit a .mcp.json file at your project root so every team member gets the same configuration:

{
  "mcpServers": {
    "rtila": {
      "command": "/Applications/RTILA.app/Contents/MacOS/rtila-engine",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "claude-code"
      ],
      "env": { "RTILA_TOKEN": "${RTILA_TOKEN}" }
    }
  }
}

Tip: The ${RTILA_TOKEN} syntax references an environment variable, keeping the secret out of version control. Each team member sets RTILA_TOKEN in their shell profile.

Verify

Run /mcp inside Claude Code, or:

claude mcp list

You should see rtila listed with its tools.

Install RTILA Skills for Claude Code

The RTILA repository includes Agent Skills that teach Claude Code how to drive the MCP server correctly — the async polling loop, analysis report interpretation, run diagnosis, and dataset reading. See MCP Workflows — Skills for Claude Code for installation instructions.

Claude Desktop

Claude Desktop is Anthropic’s desktop application for macOS and Windows.

Configuration File Location

Platform	Path
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

Configuration

macOS example:

{
  "mcpServers": {
    "rtila": {
      "command": "/Applications/RTILA.app/Contents/MacOS/rtila-engine",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "claude-desktop"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

Windows example:

{
  "mcpServers": {
    "rtila": {
      "command": "C:\\Users\\you\\AppData\\Local\\RTILA\\rtila-engine.exe",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "claude-desktop"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

⚠️ Windows: Every backslash in the command path must be doubled (\\). This is a JSON escaping requirement, not an RTILA requirement.

Apply Changes

Restart Claude Desktop after editing the configuration file. The MCP server is spawned when Claude Desktop starts.

Verify

Open a new conversation in Claude Desktop. You should see the RTILA tools available. Ask: “List my RTILA projects” — the AI should call rtila_list_projects.

Cursor

Cursor is an AI-powered code editor built on VS Code. It supports MCP servers natively.

Configuration File Location

Scope	Path
Global (all projects)	`~/.cursor/mcp.json`
Per-project	`.cursor/mcp.json` (in the project root)

Configuration

{
  "mcpServers": {
    "rtila": {
      "command": "/Applications/RTILA.app/Contents/MacOS/rtila-engine",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "cursor"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

Windows example:

{
  "mcpServers": {
    "rtila": {
      "command": "C:\\Users\\you\\AppData\\Local\\RTILA\\rtila-engine.exe",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "cursor"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

Verify

Open Cursor.
Go to Settings → MCP.
Confirm rtila appears with a green status indicator and shows 17 tools.

If the status is red, click on the server name to see the error output.

VS Code / GitHub Copilot

Visual Studio Code with the GitHub Copilot extension supports MCP servers via a .vscode/mcp.json file.

Note: VS Code uses the key servers (not mcpServers) and requires a type field.

Configuration

Create or edit .vscode/mcp.json in your workspace:

{
  "servers": {
    "rtila": {
      "type": "stdio",
      "command": "/Applications/RTILA.app/Contents/MacOS/rtila-engine",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "vscode"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

Windows example:

{
  "servers": {
    "rtila": {
      "type": "stdio",
      "command": "C:\\Users\\you\\AppData\\Local\\RTILA\\rtila-engine.exe",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "vscode"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

Verify

Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
Search for “MCP: List Servers”.
Confirm rtila appears in the list.

Windsurf

Windsurf (formerly Codeium) supports MCP servers via its own configuration file.

Configuration File Location

~/.codeium/windsurf/mcp_config.json

Configuration

The format is the same mcpServers shape used by Cursor:

{
  "mcpServers": {
    "rtila": {
      "command": "/Applications/RTILA.app/Contents/MacOS/rtila-engine",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "windsurf"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

Verify

Restart Windsurf. The MCP tools should appear in the AI assistant’s available tools.

Continue.dev

Continue is an open-source AI code assistant for VS Code and JetBrains. It supports MCP servers in its config.json.

Configuration File Location

~/.continue/config.json

Configuration

Add the MCP server to the experimental.modelContextProtocolServers array:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "/Applications/RTILA.app/Contents/MacOS/rtila-engine",
          "args": [
            "--mcp",
            "--rest-api", "http://127.0.0.1:8090",
            "--session-id", "continue"
          ]
        },
        "env": { "RTILA_TOKEN": "your-token-here" }
      }
    ]
  }
}

Cline

Cline is an AI coding assistant VS Code extension with MCP support.

Configuration

Open Cline’s settings and add the MCP server:

{
  "mcpServers": {
    "rtila": {
      "command": "/Applications/RTILA.app/Contents/MacOS/rtila-engine",
      "args": [
        "--mcp",
        "--rest-api", "http://127.0.0.1:8090",
        "--session-id", "cline"
      ],
      "env": { "RTILA_TOKEN": "your-token-here" }
    }
  }
}

Any Other Stdio Client

The RTILA MCP server speaks newline-delimited JSON-RPC 2.0 over stdio. Any client that supports stdio-based MCP servers will work. The universal configuration pattern is:

Field	Value
command	Absolute path to `rtila-engine`
args	`--mcp` followed by the flags from the Launch Flags Reference
transport	`stdio`
stdout	JSON-RPC messages only — never wrap this command in anything that prints to stdout
stderr	Diagnostics and logging — safe to capture or discard

⚠️ Critical: The MCP protocol requires stdout to contain only JSON-RPC messages. Do not wrap the rtila-engine command in a shell script, echo, or any program that writes to stdout. If the smoke test reports impure stdout lines above zero, something in your command chain is polluting stdout.

Multiple Clients on the Same Machine

You can run multiple MCP clients simultaneously, each with its own rtila-engine process. Use a different --session-id for each client to keep run records and log attribution separate:

Client	Session ID
Claude Code	`claude-code`
Claude Desktop	`claude-desktop`
Cursor	`cursor`
VS Code	`vscode`
Windsurf	`windsurf`

Each client spawns its own engine process. They all share the same database, so projects and data are visible across all clients.

Configuration Quick Reference

Client	Config File	Config Key	Restart Required?
Claude Code	CLI or `.mcp.json`	`mcpServers`	No (CLI) / Yes (file)
Claude Desktop	`claude_desktop_config.json`	`mcpServers`	Yes
Cursor	`~/.cursor/mcp.json` or `.cursor/mcp.json`	`mcpServers`	Yes
VS Code / Copilot	`.vscode/mcp.json`	`servers`	Yes
Windsurf	`~/.codeium/windsurf/mcp_config.json`	`mcpServers`	Yes
Continue.dev	`~/.continue/config.json`	`experimental.modelContextProtocolServers`	Yes
Cline	Cline settings UI	`mcpServers`	Yes

Tips and Best Practices

Tip	Why It Matters
Use absolute paths for the engine binary	Relative paths break when the client’s working directory differs
Use `env` for the token, not `args`	Command-line args are visible in process listings
Use a unique `--session-id` per client	Keeps run records and logs separate
Restart the client after config changes	Most clients only read MCP config at startup
Test with `rtila_engine_info` first	Confirms the server started with the correct configuration
On Windows, double all backslashes in JSON	JSON requires escaped backslashes
Don’t wrap the command in a shell script	Stdout pollution breaks the MCP protocol
Keep the database running	Data tools and project runs require the database

MCP Client Setup

Configuration Overview

Claude Code

Option A: CLI Command (Recommended)

Option B: Team-Shared Configuration (.mcp.json)

Verify

Install RTILA Skills for Claude Code

Claude Desktop

Configuration File Location

Configuration

Apply Changes

Verify

Cursor

Configuration File Location

Configuration

Verify

VS Code / GitHub Copilot

Configuration

Verify

Windsurf

Configuration File Location

Configuration

Verify

Continue.dev

Configuration File Location

Configuration

Cline

Configuration

Any Other Stdio Client

Multiple Clients on the Same Machine

Configuration Quick Reference

Tips and Best Practices

Option B: Team-Shared Configuration (`.mcp.json`)