Skip to content
TeamHUD Docs

MCP server

The running TeamHUD app exposes a built-in MCP server. Point your MCP client (Claude Code, Claude Desktop, Cursor, …) at it and your agent can inspect and drive the live app — read logs, widget and overlay state, stores and preferences, run searches, and send events. It’s the fastest way to build and debug a widget with an agent in the loop.

Get your connection info

Section titled “Get your connection info”

The app is the source of truth for your exact URL and token. Open Preferences → Developer → MCP. It shows:

  • the server URL and port,
  • your admin token (copy / regenerate), and
  • a ready-to-paste .mcp.json snippet.

Copy the snippet from there — it already has your live URL and token filled in.

Client config

Section titled “Client config”

The config is standard MCP (streamable HTTP). The endpoint is the server root — there is no /mcp path suffix:

{
  "mcpServers": {
    "teamhud": {
      "type": "http",
      "url": "http://localhost:28443",
      "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
    }
  }
}

Put this in your client’s MCP config (e.g. ~/.claude.json or a project .mcp.json for Claude Code; .cursor/mcp.json for Cursor). A Bearer token is required — use the admin token from the Preferences panel.

Plain HTTP on loopback

Section titled “Plain HTTP on loopback”

The server listens on 127.0.0.1 only, over plain HTTP — there is no certificate to trust. It is protected by the Bearer token and by refusing any request whose Host or Origin is not a loopback address. If your config still says https://localhost:28443, change it to http:// — same port, same token.

Ports & instances

Section titled “Ports & instances”

Two listeners, both plain HTTP: 28443, the primary, always on; and 28080, a second listener that development builds turn on and other builds keep off unless you enable it in Preferences. A packaged install uses 29443 / 29080 instead, and each extra TEAMHUD_INSTANCE shifts the ports up by one (instance 2 → 28444 / 28081). The Preferences panel always shows your exact port, so read it there rather than assuming.

What you can do

Section titled “What you can do”

The server exposes tools grouped by purpose:

  • State & introspection — widget windows and library, overlay status and DOM, interactive regions, stores, preferences, datasource status, app/system info.
  • Logs & diagnostics — recent logs (filterable), widget deliveries, audio/call diagnostics.
  • Search — run a search, list indexes and events.
  • Actions — send events, hot-reload plugins, restart, refresh widget coordination.
  • Theming — inspect and apply themes.