MCP Debugger Overview
The Hosanna MCP server lets an AI agent inspect and control a running Hosanna application through the same command-debugger proxy used by DevTools. It can inspect focus and state, drive input, query logs, trace handlers and rendering, inspect CollectionViews, take screenshots, work with Roku devices, and diagnose Hs2d games.
Components
The MCP process uses the proxy for app discovery and runtime commands. Browser and Roku actions that belong to the host use their own transports.
The MCP server does not launch the app by itself. The application must have remote debugging enabled and register with the same proxy instance. DevTools and MCP can connect at the same time.
Start a Web Session
In the application repository, ensure the selected build-config environment/profile enables:
{
"remoteDebug": {
"isEnabled": true,
"isStartServerByDefault": true,
"host": "localhost",
"webAppServerPort": 59151,
"deviceAppServerPort": 59152
},
"mcp": {
"isEnabled": true
}
}
Start the proxy and app:
npx hst debugger:start
npx hst run web dev browser
If the project keeps debugging in an explicit profile:
npx hst run web dev browser --profile local-debug
Start MCP from the agent host:
HOSANNA_MCP_ENABLED=true npx hst mcp:start
HOSANNA_MCP_ENABLED=true enables the standalone MCP process explicitly. App-side mcp.isEnabled and remoteDebug.isEnabled still come from the application's resolved build config.
Start a Device Session
Use a build environment or profile that enables device remote debugging, then run the selected target:
npx hst debugger:start
npx hst run roku debug device --device "<name-or-ip>"
HOSANNA_MCP_ENABLED=true npx hst mcp:start
The proxy host advertised to a physical device must be reachable from that device. A cloud-hosted agent usually cannot reach a device on a private LAN; use a local agent for Roku and other physical-device workflows.
MCP Command Configuration
When hosanna-mcp is available on PATH:
{
"mcpServers": {
"hosanna-debugger": {
"command": "hosanna-mcp",
"args": [],
"env": {
"HOSANNA_PROJECT_PATH": ".",
"HOSANNA_MCP_ENABLED": "true"
}
}
}
}
To resolve the binary through npm:
{
"mcpServers": {
"hosanna-debugger": {
"command": "npx",
"args": [
"-y",
"--package=@tantawowa/hosanna-tools",
"hosanna-mcp"
],
"env": {
"HOSANNA_PROJECT_PATH": ".",
"HOSANNA_MCP_ENABLED": "true"
}
}
}
}
Restart or reload the editor after changing its MCP configuration.
Ports
hst mcp:start options:
| Option | Default | Purpose |
|---|---|---|
--managementPort | 59150 | Debug-proxy HTTP management port |
--managementHost | localhost | Debug-proxy host |
--extensionPort | 59153 | Proxy extension WebSocket port |
These values must match hst debugger:start. 59151 and 59152 are the
configurable web/device base or legacy endpoints. A registering app can receive
a different per-app WebSocket port through the management API.
Verify the Connection
Start every investigation with:
health()
get_state()
health reports proxy reachability, connected apps, app types, and the primary runtime. get_state establishes the current route, focus, and compact UI state before the agent sends input.
When multiple apps are connected, pass appId rather than relying on primary-runtime selection.
Environment Variables
| Variable | Purpose |
|---|---|
HOSANNA_PROJECT_PATH | Project root used for source, build, and registry tools |
HOSANNA_MCP_ENABLED | Explicit standalone MCP enable/disable override |
HOSANNA_MANAGEMENT_PORT | Debug-proxy management port |
HOSANNA_MANAGEMENT_HOST | Debug-proxy host |
HOSANNA_EXTENSION_PORT | Proxy extension WebSocket port |
HOSANNA_ROKU_DEVICE_IP / ROKU_DEVICE_IP | Optional Roku device auto-configuration |
HOSANNA_ROKU_DEV_PASSWORD / ROKU_DEV_PASSWORD | Optional Roku screenshot/installer credential |
Do not place device passwords in committed editor configuration. Inject them from the local environment or a secret manager.