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),
  • a ready-to-paste .mcp.json snippet, and
  • when TLS is on, the exact cert-trust command for Node-based clients.

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": "https://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.

TLS / trusting the cert

Section titled “TLS / trusting the cert”

The HTTPS listener uses a self-signed certificate. Node-based clients (like Claude Code) don’t consult the OS trust store, so they’ll fail with UNABLE_TO_VERIFY_LEAF_SIGNATURE unless you either:

  • point Node at the cert with NODE_EXTRA_CA_CERTS — the Preferences panel gives you the exact one-liner for your shell/OS, or
  • use the plain-HTTP endpoint instead (http://localhost:28080), which skips cert trust entirely. Fine for localhost development.

Ports & instances

Section titled “Ports & instances”

Defaults are around 28443 (HTTPS) / 28080 (HTTP). A packaged install and additional instances use different ports — each extra TEAMHUD_INSTANCE shifts the port 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.