> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-b-sync-npm-packages-docs-bf03420.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Embedded Agent
> Add an AI agent to your website with a single custom element. The easiest way to let users interact with your WebMCP tools.
The WebMCP Embedded Agent is a drop-in AI assistant for any website. Add a custom element to your HTML, and users can interact with all the tools your site exposes via `navigator.modelContext`.
## Quick Start
```bash theme={null}
npm install @mcp-b/global @mcp-b/embedded-agent
```
```typescript "main.tsx" theme={null}
import '@mcp-b/global';
import '@mcp-b/embedded-agent/web-component';
```
```html "index.html" theme={null}
```
## How It Works
```mermaid theme={null}
sequenceDiagram
participant User
participant Agent as Embedded Agent
participant Tools as Your WebMCP Tools
User->>Agent: "Add item to cart"
Agent->>Tools: Discovers registered tools
Agent->>Tools: callTool('add_to_cart', {...})
Tools->>Tools: Execute in browser
Tools-->>Agent: Tool result
Agent-->>User: "Item added!"
```
Your website registers tools using `navigator.modelContext`, and the embedded agent can discover and call them automatically.
## Configuration
### Required Attributes
| Attribute | Description |
| ---------- | --------------------------- |
| `app-id` | Your application identifier |
| `api-base` | Your API endpoint URL |
### Optional Attributes
| Attribute | Default | Description |
| ----------- | -------- | ---------------------------------------------------- |
| `view-mode` | `"pill"` | Display mode: `"pill"`, `"panel"`, or `"fullscreen"` |
## Development Mode
During development, you can use your own API keys to test without cost:
```html theme={null}
```
Never expose API keys in production. Development keys are for local testing only.
## Registering Tools
The embedded agent automatically discovers tools registered on your page:
```tsx "ProductPage.tsx" twoslash theme={null}
import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';
export function ProductPage() {
useWebMCP({
name: 'add_to_cart',
description: 'Add a product to the shopping cart',
inputSchema: {
productId: z.string().describe('Product ID to add'),
quantity: z.number().min(1).describe('Quantity to add')
},
handler: async ({ productId, quantity }) => {
await addToCart(productId, quantity);
return { success: true, message: `Added ${quantity} item(s)` };
}
});
return ...
;
}
```
For vanilla JavaScript:
```javascript "app.js" theme={null}
import '@mcp-b/global';
navigator.modelContext.registerTool({
name: 'search_products',
description: 'Search the product catalog',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string', description: 'Search query' }
},
required: ['query']
},
async execute({ query }) {
const results = await searchProducts(query);
return {
content: [{ type: 'text', text: JSON.stringify(results) }]
};
}
});
```
## Loading via CDN
You can also load the embedded agent without a build step:
### ESM
```html theme={null}
```
### IIFE (No Module Support)
```html theme={null}
```
## View Modes
The agent supports three display modes:
A compact floating button that expands into a chat interface. Best for minimal UI impact.
```html theme={null}
```
A slide-out panel anchored to the side of the screen. Good for extended interactions.
```html theme={null}
```
Takes over the entire viewport. Ideal for dedicated AI experiences.
```html theme={null}
```
## Security
The embedded agent runs in your page's context and has access to the same tools your users can access. All tool executions happen client-side.
* Tools inherit your website's permissions and origin policies
* User authentication is handled through your `app-id` configuration
* API keys are never exposed in production builds
Review comprehensive security guidelines for WebMCP implementations
## Next Steps
Learn how to create powerful tools for the agent to use
Use the `useWebMCP` hook for easier tool registration
Patterns for building effective AI-powered features
See complete working implementations