WebMCP Documentation

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

Install the packages

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

Initialize in your app entry

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

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

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:

<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:

Pill
Panel
Fullscreen

A compact floating button that expands into a chat interface. Best for minimal UI impact.

<webmcp-agent view-mode="pill" ... />

A slide-out panel anchored to the side of the screen. Good for extended interactions.

<webmcp-agent view-mode="panel" ... />

Takes over the entire viewport. Ideal for dedicated AI experiences.

<webmcp-agent view-mode="fullscreen" ... />

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

​Quick Start

​How It Works

​Configuration

​Required Attributes

​Optional Attributes

​Development Mode

​Registering Tools

​Loading via CDN

​ESM

​IIFE (No Module Support)

​View Modes

​Security

Security Best Practices

​Next Steps

Tool Registration

React Integration

Best Practices

Examples

Quick Start

How It Works

Configuration

Required Attributes

Optional Attributes

Development Mode

Registering Tools

Loading via CDN

ESM

IIFE (No Module Support)

View Modes

Security

Next Steps