Skip to main content
Use this guide for the canonical embed contract.

​
Auth contract (current)

  • publishableKey: required
  • idToken: optional
<char-agent> handles ticket exchange internally through POST /api/auth/pk-ticket.

​
Install

npm install @mcp-b/char

import "@mcp-b/char/web-component";

​
Key-only embed

<char-agent publishable-key="pk_live_..."></char-agent>
This gives org-scoped access without per-user identity.

​
Per-user identity embed

import "@mcp-b/char/web-component";
import type { CharAgentElement } from "@mcp-b/char/web-component";

const agent = document.querySelector("char-agent") as CharAgentElement;
const idToken = await getIdTokenForCurrentUser();

agent.connect({
  publishableKey: "pk_live_...",
  idToken,
});

​
React (@mcp-b/char-react)

import { CharAgent } from "@mcp-b/char-react";

export function SupportWidget({ idToken }: { idToken?: string }) {
  return (
    <CharAgent
      publishableKey="pk_live_..."
      idToken={idToken}
      style={{ width: 420, height: 640 }}
    />
  );
}

​
Security notes

  • Keep idToken out of DOM attributes; pass it via connect()/setAuth().
  • Treat publishable keys as public embed credentials and rotate if exposed unexpectedly.
  • Restrict key usage with allowed origins in dashboard settings.

​
Troubleshooting

  • MISSING_PUBLISHABLE_KEY: provide publishable-key or connect({ publishableKey })
  • INVALID_KEY: key is revoked/invalid
  • ORIGIN_NOT_ALLOWED: add the origin to allowed origins/domains for that key
  • INVALID_TOKEN/TOKEN_EXPIRED: refresh user session and pass a fresh idToken