`<char-agent>`

<char-agent> custom element. Creates an iframe pointing to the SaaS app’s /embed/ entrypoint and relays auth, styles, dark mode, display mode, and MCP messages via postMessage. Uses a unified char-context message with diffing (only changed fields are sent) instead of separate messages per concern.

Registration and import

import '@mcp-b/char/web-component'

import { registerChar } from '@mcp-b/char/web-component'
registerChar()

Auth and connection helpers

const agent = document.querySelector('char-agent')

agent?.setAuth({ publishableKey, idToken }) // convenience wrapper
agent?.connect({ publishableKey, idToken }) // explicit connect
agent?.setHostContext({ displayMode: 'inline' })
agent?.disconnect()

setAuth
connect
disconnect
setHostContext

Attributes

Attribute	Type	Default	Description
`api-base`	`string`	`https://app.usechar.ai`	Overrides the Char API base URL.
`display-mode`	`"inline" \| "fullscreen" \| "pip"`	`pip`	Requested display mode for the embedded surface.
`enable-debug-tools`	`boolean`	`false`	Enables iframe debug tools when supported.
`publishable-key`	`string`	n/a	Publishable key used to resolve org context.

Properties

Property	Type	Description
`apiBase`	`string \| undefined`	React-friendly property form of `api-base`.
`publishableKey`	`string \| undefined`	Publishable key for org identification. Set via `publishable-key` attribute or JS property.

Methods

Method	Returns	Summary
`setAuth()`	`void`	Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth.
`connect()`	`void`	Connect to the Char agent with authentication. The token is stored as a JavaScript property (not as a DOM attribute), preventing exposure to DOM inspection and session replay tools.
`disconnect()`	`void`	Disconnect from the Char agent. Clears pending auth state and posts a disconnect message to the iframe.
`setHostContext()`	`void`	Update the host context sent to the iframe. Only changed fields are transmitted (diffing pattern).

`setAuth(options: ConnectOptions | null): void`

Convenience method for declarative wrappers. Applies auth when provided, otherwise clears auth. Parameters:

options (ConnectOptions | null): Auth payload to connect, or null to disconnect.

Returns: void

`connect(options: ConnectOptions): void`

Connect to the Char agent with authentication. The token is stored as a JavaScript property (not as a DOM attribute), preventing exposure to DOM inspection and session replay tools. Parameters:

options (ConnectOptions): Authentication payload.

Returns: void

`disconnect(): void`

Disconnect from the Char agent. Clears pending auth state and posts a disconnect message to the iframe. Returns: void

`setHostContext(hostContext: CharHostContext): void`

Update the host context sent to the iframe. Only changed fields are transmitted (diffing pattern). Parameters:

hostContext (CharHostContext): Partial host context patch to merge and emit.

Returns: void

Events

Event	Detail	Description
`char-initialized`	`void`	Emitted when the embedded runtime has initialized.
`char-close`	`void`	Emitted when the embedded UI asks the host to close.
`char-error`	`CharErrorDetail`	Emitted on host/runtime bridge errors.
`char-size-changed`	`CharSizeChangedDetail`	Reports embedded content sizing updates.
`char-request-display-mode`	`CharRequestDisplayModeDetail`	Requests a host-side display mode change.
`char-open-link`	`CharOpenLinkDetail`	Requests the host to open an external URL.

Slots

None.

CSS Custom Properties

Supports the full Char design-token surface documented in CSS Variables Reference.

CSS Parts

None.

API Reference

SDK Reference

Agent Reference

MCP Reference

Security Reference

Auth

OAuth

Subscriptions

End Users

Users

Organizations

Organization Skills

User Scripts

Directories

Plan Tiers

Threads

Usage Analytics

Identity Providers

Governance

GitHub Apps

Publishable Keys

OAuth Discovery

<char-agent>

`<char-agent>`

Registration and import

Auth and connection helpers

Attributes

Properties

Methods

`setAuth(options: ConnectOptions | null): void`

`connect(options: ConnectOptions): void`

`disconnect(): void`

`setHostContext(hostContext: CharHostContext): void`

Events

Slots

CSS Custom Properties

CSS Parts

​<char-agent>

​Registration and import

​Auth and connection helpers

​Attributes

​Properties

​Methods

​setAuth(options: ConnectOptions | null): void

​connect(options: ConnectOptions): void

​disconnect(): void

​setHostContext(hostContext: CharHostContext): void

​Events

​Slots

​CSS Custom Properties

​CSS Parts

`<char-agent>`

Registration and import

Auth and connection helpers

Attributes

Properties

Methods

`setAuth(options: ConnectOptions | null): void`

`connect(options: ConnectOptions): void`

`disconnect(): void`

`setHostContext(hostContext: CharHostContext): void`

Events

Slots

CSS Custom Properties

CSS Parts