Skip to main content
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

1

Install the packages

npm install @mcp-b/global @mcp-b/embedded-agent
2

Initialize in your app entry

import '@mcp-b/global';
import '@mcp-b/embedded-agent/web-component';
3

Add the custom element

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
  <webmcp-agent
    app-id="your-app-id"
    api-base="https://your-api-endpoint"
    view-mode="pill"
  />
</body>

​
How It Works

Your website registers tools using navigator.modelContext, and the embedded agent can discover and call them automatically.

​
Configuration

​
Required Attributes

AttributeDescription
app-idYour application identifier
api-baseYour API endpoint URL

​
Optional Attributes

AttributeDefaultDescription
view-mode"pill"Display mode: "pill", "panel", or "fullscreen"

​
Development Mode

During development, you can use your own API keys to test without cost: 
<webmcp-agent
  app-id="dev"
  api-base="http://localhost:3001"
  openai-api-key="sk-..."
  anthropic-api-key="sk-ant-..."
  view-mode="panel"
/>
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: 
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 <div>...</div>;
}
For vanilla JavaScript: 
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

<script type="module">
  import 'https://unpkg.com/@mcp-b/global@latest/dist/index.esm.js';
  import 'https://unpkg.com/@mcp-b/embedded-agent@latest/dist/web-component.esm.js';
</script>

<webmcp-agent app-id="your-app-id" api-base="https://api.example.com" />

​
IIFE (No Module Support)

<script src="https://unpkg.com/@mcp-b/global@latest/dist/index.iife.js"></script>
<script src="https://unpkg.com/@mcp-b/embedded-agent@latest/dist/web-component.iife.js"></script>

<webmcp-agent app-id="your-app-id" api-base="https://api.example.com" />

​
View Modes

The agent supports three display modes:
A compact floating button that expands into a chat interface. Best for minimal UI impact.
<webmcp-agent view-mode="pill" ... />

​
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

Security Best Practices

Review comprehensive security guidelines for WebMCP implementations

​
Next Steps

Tool Registration

Learn how to create powerful tools for the agent to use

React Integration

Use the useWebMCP hook for easier tool registration

Best Practices

Patterns for building effective AI-powered features

Examples

See complete working implementations