@mcp-b/char

An Intercom-like AI chat widget with MCP tool support and voice mode. Drop it into your app and you're done.

Styles are isolated using Shadow DOM. Customize appearance by setting CSS variables on the host page.

Build Architecture

This package provides the custom element in two formats:

| Export | Format | Use Case |
|--------|--------|----------|
| @mcp-b/char / @mcp-b/char/web-component | ESM web component | Bundlers, monorepo dev |
| @mcp-b/char/standalone | IIFE web component |
`

$3

`tsx
import { useRef, useEffect } from "react";
import "@mcp-b/char/web-component";
import type { CharAgentElement } from "@mcp-b/char/web-component";

const authToken = session?.idToken ?? "";
const agentRef = useRef(null);

useEffect(() => {
const agent = agentRef.current ?? document.querySelector("char-agent");

if (!agent) {
const newAgent = document.createElement("char-agent");
document.body.appendChild(newAgent);
// Connect after element is in DOM
(newAgent as CharAgentElement).connect({ idToken: authToken });
} else if (authToken) {
(agent as CharAgentElement).connect({ idToken: authToken });
}

// Set other attributes (these don't contain sensitive data)
agent?.setAttribute("dev-mode", JSON.stringify({ useLocalApi: true }));
agent?.setAttribute("enable-debug-tools", String(import.meta.env.DEV));
}, [authToken]);

return ;
`

$3

Use defer for best performance - it loads the script without blocking page rendering:

`html





`

Alternative CDN (jsdelivr):

`html

`

Pin to a specific version for production:

`html

`

$3

`html

dev-mode='{"anthropicApiKey": "sk-ant-..."}'
enable-debug-tools="true"
>


`

SSR Frameworks (Astro, Next.js, etc.)

Char requires a browser environment — it uses Shadow DOM, custom elements, and other browser APIs. In SSR frameworks, you must ensure Char only renders on the client.

$3

Use client:only="react" to skip server-side rendering entirely:

`astro
---
import { Char } from '@mcp-b/char'
---

client:only="react"
devMode={{ anthropicApiKey: import.meta.env.PUBLIC_ANTHROPIC_API_KEY }}
open={true}
/>
`

client:load or client:visible will not work because Astro still attempts to render the component on the server first. client:only="react" skips SSR entirely and renders only in the browser.

$3

Use dynamic imports with ssr: false:

`tsx
import dynamic from 'next/dynamic'

const Char = dynamic(() => import('@mcp-b/char').then(m => ({ default: m.Char })), {
ssr: false,
})

export default function Page() {
return
}
`

Props / Attributes

| Prop | Attribute | Type | Description |
|------|-----------|------|-------------|
| - | - | method | connect({ idToken }) - Secure authentication (token not in DOM) |
| - | - | method | connect({ ticketAuth }) - SSR-friendly authentication (pre-fetched ticket) |
| - | - | method | disconnect() - Clear authentication |
| open | open | boolean | Controlled open state (optional) |
| devMode | dev-mode | object/JSON | Development mode config (optional) |
| enableDebugTools | enable-debug-tools | boolean | Enable debug tools (default: false) |

Customization

Customize appearance by setting CSS variables on the host page:

`css
char-agent {
/ Brand colors /
--wm-color-primary: #8b5cf6;
--wm-color-primary-foreground: #ffffff;

/ Layout /
--wm-radius: 12px;
--wm-font-sans: 'Inter', sans-serif;

/ Backgrounds /
--wm-color-background: #ffffff;
--wm-color-foreground: #1a1a1a;
--wm-color-muted: #f5f5f5;

/ Messages /
--wm-user-bubble-bg: #8b5cf6;
--wm-user-bubble-text: #ffffff;
--wm-assistant-bubble-bg: #f5f5f5;
--wm-assistant-bubble-text: #1a1a1a;

/ Composer /
--wm-composer-bg: #ffffff;
--wm-composer-border: #e5e5e5;
--wm-composer-button-bg: #8b5cf6;

/ Tools /
--wm-tool-bg: #f9fafb;
--wm-tool-border: #e5e7eb;
--wm-tool-approve-bg: #10b981;
--wm-tool-deny-bg: #ef4444;

/ Code blocks /
--wm-code-bg: #1e1e1e;
--wm-code-text: #d4d4d4;

/ Font sizes /
--wm-font-size-xs: 0.75rem;
--wm-font-size-sm: 0.875rem;
--wm-font-size-base: 1rem;
--wm-font-size-lg: 1.125rem;
}

/ Dark mode /
char-agent.dark {
--wm-color-background: #1a1a1a;
--wm-color-foreground: #ffffff;
--wm-color-muted: #2a2a2a;
/ ... other dark mode overrides /
}
`

Development Mode

Use your own API keys during development (stateless):

`html
dev-mode='{"anthropicApiKey":"sk-ant-...","openaiApiKey":"sk-...","useLocalApi":true}'
>
`

Development modes:
- anthropicApiKey: Use your own Anthropic API key (falls back to Gemini if not provided)
- openaiApiKey: Enable voice mode with your OpenAI key
- useLocalApi: Point to localhost instead of production API

Common combinations:
- { useLocalApi: true } - Internal monorepo development
- { anthropicApiKey: "sk-ant-..." } - External dev with your own key
- { anthropicApiKey: "...", openaiApiKey: "...", useLocalApi: true } - Full stack local dev

Performance

$3

Always use defer or async when embedding the standalone script to avoid blocking page rendering:

`html





`

When to use which:
- defer (recommended) - Script executes after HTML is parsed, preserves execution order
- async - Script executes as soon as it loads, good for independent widgets

$3

Speed up loading by adding a preconnect hint in your :

`html

`

Features

- MCP Tool Support - Connect to any MCP server
- Voice Mode - Talk to your AI assistant
- Action-First UI - Shows what the AI is doing
- Shadow DOM Isolation - Styles don't leak in or out
- Stateful Sessions - Messages persist across page refreshes (when authToken is provided)
- CSS Variable Theming - Customize appearance without JavaScript

Migration Guide

$3

Removed props:
- apiKey / userId - Replaced by authToken (use your existing IDP token)
- appId - No longer needed (removed dead code)
- siteId - Org-level routing in SSO-first mode (no site scoping)
- theme - Use CSS variables instead (see Customization section)
- isolateStyles - Always enabled (Shadow DOM is always used)
- disableShadowDOM - Removed (Shadow DOM is always enabled)

Migration examples:

`html

app-id="app_123"
site-id="site_123"
api-key="sk_live_xxx"
theme='{"primaryColor":"#ff0000","mode":"dark"}'
isolate-styles="false"
>



`

Benefits:
- Smaller bundle size (~200 lines removed)
- Simpler API (fewer required attributes)
- More flexible styling (CSS variables work everywhere)
- Consistent Shadow DOM isolation (no edge cases)
- No API keys to manage (uses existing IDP tokens)

Development

`bash
pnpm --filter @mcp-b/char dev # Watch TS build
pnpm --filter @mcp-b/char dev:css # Watch Tailwind CSS
pnpm --filter @mcp-b/char storybook # http://localhost:6006
pnpm --filter @mcp-b/char build
pnpm --filter @mcp-b/char check:types
pnpm --filter @mcp-b/char test
``