AI integration via MCP (rk mcp)

The RSG 2.0 SDK includes a Model Context Protocol (MCP) server that gives AI assistants (for example, GitHub Copilot, Claude, and Cursor) direct access to SDK operations, such as building apps, deploying to devices, sending remote control keys, capturing screenshots, and decoding stack traces.

You can run the server in two modes: stdio mode, where your editor spawns rk mcp, or server mode, where your editor connects to a persistent rk server.

This document covers transports and editor configuration. The generated MCP reference documents the tools. An AI agent follows the packaged mcp-setup skill, which rk update-ai-context installs, to set this up. The loop that the agent runs afterwards is the mcp-ai-dev-loop skill.

The following table compares the two transport modes:

Characteristic	Stdio mode	Server mode
How it runs	Spawned as a child process by VS Code	Persistent HTTP server (`rk server`)
Lifetime	Tied to the VS Code window	Independent; survives window restarts
Setup	One JSON file	Requires starting `rk server` first
Shared access	VS Code only	Any MCP client and automation tools
Best for	A single editor	Teams, continuous integration (CI), multi-client setups

The two modes are not mutually exclusive, and the distinction is narrower than the table suggests. The rk mcp command checks for a running server on every request and forwards the request to it. It falls back to handling the call in-process only when it does not find a server or cannot reach it.

A call that the server received is never re-run in-process. If the answer does not arrive, rk mcp returns an error that says the call may still be running there. When the server answers with an HTTP error that does not have a JSON-RPC body (403 HOST_NOT_ALLOWED, a 408 timeout, or a 429 from the rate limiter), rk mcp returns a JSON-RPC error for each request; therefore, the client never waits for a reply that cannot arrive.

The rk mcp command relays requests under the Mcp-Session-Id that the server issued to it. That ID stays valid across server restarts. The command opens a new session on its own only when the server refuses the ID, for example after someone deleted or replaced the machine's session key file.

As a result, a stdio entry with rk server running already has the full tool surface, including server-only tools. You do not need to rewrite the config when you start a server. You should point a client at the HTTP endpoint when something else needs the same backend, not to unlock tools.

Stdio mode (recommended for most users)

VS Code spawns rk mcp as a subprocess. The MCP server starts when VS Code opens and stops when the window closes. You do not need to manage a separate server process.

Setting up stdio mode

Create .vscode/mcp.json in your workspace root:

{
    "servers": {
        "roku-sdk-tools": {
            "type": "stdio",
            "command": "pnpm",
            "args": ["exec", "rk", "mcp"]
        }
    }
}

Restart VS Code (or reload the window) to make the tools available to your AI assistant.

The runner must match your project. For npm, the same entry uses "command": "npx" with ["rk", "mcp"]. Either entry resolves rk from node_modules/.bin in a project that depends on @roku-sdk/tooling. The difference between them is a fraction of a second, which the client pays when it spawns the process, not on each tool call. A runner that cannot see the project's node_modules and goes to the registry instead costs real time.

Verifying that the tools work

Open GitHub Copilot Chat and ask:

"What Roku devices do I have configured?"

The AI calls list_devices and returns your device list. If it does not, check Output > MCP for error messages.

Server mode (multi-client and long-running)

In server mode, rk server runs as a persistent HTTP process. VS Code connects to its MCP HTTP endpoint instead of spawning a subprocess.

You can use server mode in the following cases:

You want the server to persist across VS Code window restarts or reloads.
You are sharing the MCP backend with other tools (automation frameworks, test runners, and other MCP clients such as Claude Desktop).
You are running rk logs for log collection (logs require a persistent server, and the process loses them if it restarts).

Step 1: Starting the server

Start rk server in a terminal or as a daemon:

# Foreground (visible output, stops when you close the terminal)
npx rk server

# Daemon (detached background process)
npx rk server start --daemon

Check that the server is healthy and find the port:

npx rk server status
# rk server running at http://localhost:3941/api (pid 12345, rkRoot: /Users/you/workspace)

The server derives the port from a hash of the workspace root path; therefore, the port is not always the same. You can use rk server status to find the actual port for your workspace, or you can start the server with a fixed port by using --port so that you can write the port in .vscode/mcp.json:
npx rk server start --daemon --port 3737

The server automatically exits after 240 minutes of inactivity (configurable with --timeout). You can use --daemon for a persistent background process.

Step 2: Configuring VS Code to use the HTTP endpoint

Create .vscode/mcp.json in your workspace root, substituting the actual port from rk server status (or the --port value you chose):

{
    "servers": {
        "roku-sdk-tools": {
            "type": "http",
            "url": "http://127.0.0.1:<port>/mcp"
        }
    }
}

VS Code connects over HTTP instead of spawning a process. The MCP tools remain available even if you reload the VS Code window, as long as the server process is still running.

Stopping the server

The following command stops the server:

npx rk server stop

Configuring Cursor and other editors

Cursor uses an mcpServers key (not servers). The same two modes apply.

For stdio mode, use .cursor/mcp.json:

{
    "mcpServers": {
        "roku-sdk-tools": {
            "command": "pnpm",
            "args": ["exec", "rk", "mcp"]
        }
    }
}

For server mode, use .cursor/mcp.json:

{
    "mcpServers": {
        "roku-sdk-tools": {
            "url": "http://127.0.0.1:<port>/mcp"
        }
    }
}

Replace <port> with the value from npx rk server status, or start the server with --port <port> to fix the port.

Available tools

See the generated MCP tool reference for more information about tool names, parameters, and results.

Example prompts

You can describe operations in plain language:

"What Roku devices do I have?"
"Deploy the baseline-app example to my active device"
"Build the trivia-stages app"
"Press the Home button on my Roku"
"Navigate down three times and select"
"Capture a screenshot and tell me what is on screen"
"Show me the current UI hierarchy"
"What is the developer ID of my active Roku?"
"Decode this stack trace: ..."
"Reboot my active Roku device"
"Check whether Living Room Roku has a firmware update available"
"Sign the package for trivia-stages with password 1234"
"Start a log session on Bailey and show me the last 50 lines"

Troubleshooting

The following list describes problems and their fixes.

If the tools do not appear in your AI assistant, try the following:

Check Output > MCP in VS Code for connection errors.
In stdio mode, verify that npx rk mcp runs without error in a terminal from the workspace root.
In server mode, run npx rk server status to confirm that the server is running.

If you see "command not found" or exit code 127, try the following:

Verify that @roku-sdk/tooling is installed by running pnpm install in the workspace root.
Verify that node_modules/.bin/rk exists.

If the tools work in server mode but stop responding after a while, try the following:

Restart the server with npx rk server start --daemon, because the server stops after its inactivity timeout (default: 240 minutes).
Run npx rk server status to check the server.

If the tools disconnect in stdio mode when you reload VS Code, the window reload restarted the subprocess. If you need persistence, switch to server mode.