Add the Char agent to your web application using npm or a script tag.
Installation
Choose your preferred installation method:
Add the script to your HTML:<script src="https://unpkg.com/@mcp-b/embedded-agent/dist/web-component-standalone.iife.js" defer></script>
npm install @mcp-b/embedded-agent
import "@mcp-b/embedded-agent/web-component";
yarn add @mcp-b/embedded-agent
pnpm add @mcp-b/embedded-agent
Basic Usage
Add the custom element to your page:
<webmcp-agent></webmcp-agent>
Authenticating Users
Pass your IDP’s JWT token to enable authenticated sessions:
<webmcp-agent auth-token="eyJhbGciOi..."></webmcp-agent>
Without auth-token, the agent requires anthropic-api-key for anonymous mode (localhost development only). See Deployment Tiers for details. Framework Integration
import "@mcp-b/embedded-agent/web-component";
function App({ idToken }) {
return <webmcp-agent auth-token={idToken} />;
}
<template>
<webmcp-agent :auth-token="idToken" />
</template>
<script setup>
import "@mcp-b/embedded-agent/web-component";
const props = defineProps(['idToken']);
</script>
import "@mcp-b/embedded-agent/web-component";
const agent =
document.querySelector("webmcp-agent") ??
document.createElement("webmcp-agent");
if (!agent.isConnected) {
document.body.appendChild(agent);
}
agent.setAttribute("auth-token", idToken);
Controlling Open State
Open or close the agent programmatically:
const agent = document.querySelector("webmcp-agent");
// Open the agent
agent?.setAttribute("open", "true");
// Close the agent
agent?.setAttribute("open", "false");
import { useState } from "react";
function App({ idToken }) {
const [open, setOpen] = useState(false);
return (
<>
<button onClick={() => setOpen(true)}>Open Agent</button>
<webmcp-agent auth-token={idToken} open={open} />
</>
);
}
Development Mode (Anonymous)
For local development without IDP setup, use your own API key:
<webmcp-agent anthropic-api-key="sk-ant-..."></webmcp-agent>
Anonymous mode only works from localhost origins. Never embed API keys in production code—they’re visible to users.
Script Loading
The defer attribute ensures the script loads in parallel without blocking page rendering:
<!-- Recommended: defer loads async, executes after DOM ready -->
<script src="https://unpkg.com/@mcp-b/embedded-agent/dist/web-component-standalone.iife.js" defer></script>
Preconnect Hint
Speed up loading by adding a preconnect hint in your <head>:
<link rel="preconnect" href="https://unpkg.com" crossorigin>
Bundle Sizes
| Build | Size | Gzipped |
|---|
| ESM (npm) | ~560 KB | ~115 KB |
| Standalone (script tag) | ~2.2 MB | ~400 KB |
Next steps
See also
