MCP Debugger Overview

The Hosanna MCP debugger lets AI agents inspect and control a running Hosanna app. It is provided by @tantawowa/hosanna-tools as hosanna-mcp and hst run:mcp.

The MCP server connects to the same hst run:debugger proxy used by the DevTools extension. It can inspect state, send remote keys, navigate views, query logs, take screenshots, trace handlers, inspect CollectionViews, diagnose problems, and replay UI recordings.

MCP and DevTools are peers on the same debugger proxy, so agents and humans can inspect the same running app.

Architecture

Agent / editor
  |
  | stdio MCP
  v
hosanna-mcp / hst run:mcp
  |
  | HTTP management API :59150
  v
hst run:debugger
  |
  | WebSocket :59151 / :59152
  v
Web or Roku Hosanna app

The DevTools extension can be open at the same time. MCP and DevTools share the proxy and protocol, and the extension can stream CollectionView recording batches back to MCP for analysis.

Start Locally

Create assets/meta/debug-flags.dev.json:

{
  "remoteDebug": {
    "isEnabled": true,
    "isStartServerByDefault": true,
    "host": "localhost",
    "webAppServerPort": 59151,
    "deviceAppServerPort": 59152
  },
  "mcp": {
    "isEnabled": true
  }
}

Run the app and proxy:

npx hst run:debugger
npm run dev

Start MCP from your agent host:

npx hst run:mcp

hst run:mcp --help exposes these options:

Option	Default	Purpose
--managementPort	59150	debug proxy management port
--managementHost	localhost	debug proxy host
--extensionPort	59153	extension/proxy WebSocket port

Cursor MCP Configuration

For local Cursor, add .cursor/mcp.json:

{
  "mcpServers": {
    "hosanna-debugger": {
      "command": "npx",
      "args": ["hst", "run:mcp"],
      "env": {
        "HOSANNA_PROJECT_PATH": "."
      }
    }
  }
}

Restart Cursor or reload the window after editing MCP config.

For Cloud Agents, configure a Command MCP server in the Cursor dashboard and provide the same command. Use HOSANNA_PROJECT_PATH=. when the agent runs in the app repo.

Bootstrap For Cloud Agents

The easiest bootstrap is:

npx hst env:cloud-agent-setup --start-debugger --start-app

This restores debug flags, patches remote debug defaults for agent use, starts the debugger proxy, and optionally starts npm run dev.

The command expects DEBUG_FLAGS_DEV_BASE64 to exist in the cloud-agent environment. Generate it locally with:

npx hst ci:extract-config

Then store the output as a Cursor/GitHub secret.

Verify

Start with health. A healthy session should show:

• management server reachable
• one or more connected apps
• app IDs and app types
• MCP enabled
• proxy ports

Then call get_state to establish the current focus, route, and CollectionView state.

Common Environment Variables

Variable	Purpose
HOSANNA_PROJECT_PATH	project root for debug flag lookup
HOSANNA_MCP_ENABLED	overrides mcp.isEnabled
HOSANNA_MANAGEMENT_PORT	MCP management port override
HOSANNA_EXTENSION_PORT	MCP extension port override
HOSANNA_ROKU_DEVICE_IP / ROKU_DEVICE_IP	Roku target for device tools
HOSANNA_ROKU_DEV_PASSWORD / ROKU_DEV_PASSWORD	Roku dev password for screenshots and install operations

Cloud agents generally cannot reach physical Roku devices on your local network. Use web targets for cloud debugging and local agent sessions for device work.