@brander/mcp-tools

Your MCP server answers with runtime-generated, branded interactive screens — in one line.

@brander/mcp-tools registers a generate_screen tool on your MCP server that renders 15 certified branded element types (charts, tables, grids, forms, and more) — plus custom elements your team creates in Vibe Studio — at call time, in your brand's colors, fonts, and styling — directly inside Claude, ChatGPT, and other MCP-compatible hosts.

Quick Start

npm install @brander/mcp-tools

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { registerBranderTools } from "@brander/mcp-tools";

const server = new McpServer({ name: "my-app", version: "1.0.0" });

// Register your own business tools...
// server.registerTool("search_products", { ... }, handler);

// One line — adds branded UI rendering
await registerBranderTools(server, {
  projectId: process.env.BRANDER_PROJECT_ID!,
  apiKey: process.env.BRANDER_API_KEY!,
});

await server.connect(new StdioServerTransport());

What It Does

When you call registerBranderTools(server, config), it adds:

1. generate_screen tool — the AI uses this to render branded UI instead of writing raw text. Accepts an array of elements with typed props.
2. MCP App resource — a self-contained HTML renderer (React + MUI) that the host loads to display the elements in a sandboxed iframe.

Your brand settings (colors, fonts, layout, dark mode) are loaded from the BranderUX API at startup and applied to every rendered screen. API credentials stay server-side — they are never sent to the client.

Built-in Element Types

| Element | Description | |---|---| | header | Page title with subtitle | | chat-bubble | Text/markdown response | | stats-grid | KPI cards with trends | | data-table | Sortable, filterable table | | line-chart | Time series chart | | pie-chart | Proportional data | | bar-chart | Category comparison | | item-grid | Product/item cards | | item-card | Single item detail card | | image | Image display | | video | Video player (direct + YouTube) | | details-data | Key-value detail sections | | form | Dynamic input form | | button | Action/link button | | alert | Notification banner |

You can also create custom element types through the BranderUX dashboard.

Configuration

interface BranderToolsConfig {
  /** BranderUX project ID */
  projectId: string;

  /** Project API key (bux_pk_xxx) */
  apiKey: string;

  /** API base URL (defaults to https://branderux.com) */
  apiBaseUrl?: string;

  /** Path to local brandSettings.json for development */
  brandSettingsPath?: string;
}

Legacy bux_dp_ design-partner keys are still accepted during the migration window.

Host Setup

Claude Desktop

{
  "mcpServers": {
    "my-app": {
      "command": "node",
      "args": ["/path/to/your/dist/index.js"],
      "env": {
        "BRANDER_PROJECT_ID": "your_project_id",
        "BRANDER_API_KEY": "bux_pk_your_key"
      }
    }
  }
}

Claude.ai / ChatGPT (Remote)

For remote MCP servers, use streamable HTTP transport. See the demo server for a full reference implementation.

How It Works

1. At startup, registerBranderTools loads your project's brand settings from the BranderUX API
2. It registers the generate_screen tool with Zod schemas for all element types
3. It registers an MCP App resource — a single-file HTML bundle containing all React components
4. When the AI calls generate_screen, it returns structured data + a reference to the HTML resource
5. The host loads the HTML resource and renders branded UI with your data
6. During streaming, elements appear progressively as the AI generates them

Interactive Elements

Elements support click interactions via clickQuery. When a user clicks a table row, chart segment, or card, the query is sent back to the AI to continue the conversation:

// The AI generates this tool call:
generate_screen({
  elements: [{
    elementType: "item-grid",
    props: { items: [...] },
    clickQuery: "Show details for [title] including specs and reviews"
  }]
})

Placeholders like [title], [id], [name] are filled with the clicked element's data.

Example

See @brander/mcp-demo for a full reference implementation showcasing all 15 element types with demo scenarios.

License

MIT