WebMCP Documentation - AI-Powered Web Tools

Overview

This guide covers four primary connection methods, each suited to different use cases and architectures. Whether you’re building a website that exposes tools to users’ local AI clients, or an embedded application that agents control directly, you’ll find the right approach here. We’ll compare setup complexity, capabilities, and security considerations for each method.

Connection Methods

There are four primary ways to connect agents to WebMCP tools:

Browser Agents

Native browser support (coming soon)

Frontend AI Frameworks

Direct integration with your website’s AI

MCP-B Extension

Browser extension for any website

Local MCP Clients

Claude Desktop, VSCode, and more

1. Browser Agents (Native Support)

What Are Browser Agents?

Browser agents are AI assistants built directly into web browsers. These agents have native access to the web platform APIs, including WebMCP’s navigator.modelContext.

Current Status

Chrome and Edge are both planning native implementations of browser agents that will support WebMCP tools out of the box.

When these implementations ship, any website using WebMCP will automatically work with the browser’s built-in AI assistant - no extension or additional setup required.

How It Works

Browser agents will be able to:

Discover tools registered via navigator.modelContext.registerTool()
Call tools with user permission
Receive results directly
Respect the same origin policies and authentication

Getting Ready

To prepare for browser agent support:

Use the standard navigator.modelContext API to register tools

Follow security best practices

Review security guidelines for tool validation and permissions

Test with MCP-B Extension

Use the MCP-B Extension to test how agents will interact with your tools

2. Frontend AI Frameworks

What Are Frontend AI Frameworks?

Frontend AI frameworks let you build AI-powered features directly into your website or web application. These frameworks can call WebMCP tools from your site’s own AI agent.

Frontend Tool Calling Guide

Complete guide to integrating WebMCP with frontend AI frameworks

Supported Frameworks

Assistant-UI

React framework for building AI assistants

AG-UI

Agentic UI framework with tool support

How It Works

Your website’s AI agent calls WebMCP tools directly in the browser:

Quick Example

import { useWebMCP } from '@mcp-b/react-webmcp';
import { z } from 'zod';

// Register a tool
useWebMCP({
  name: 'add_to_cart',
  description: 'Add product to cart',
  inputSchema: {
    productId: z.string(),
    quantity: z.number().min(1)
  },
  handler: async (input) => {
    await addToCart(input.productId, input.quantity);
    return { success: true };
  }
});

Your frontend AI can then discover and call this tool automatically.

3. MCP-B Extension

What Is the MCP-B Extension?

The MCP-B Extension is a browser extension that:

Collects WebMCP tools from all open tabs
Provides AI agents specialized for different tasks
Lets you create custom tools via userscripts
Bridges tools to local MCP clients

Extension Guide

Complete guide to the MCP-B browser extension

Built-in Agents

The extension includes four specialized agents:

Userscript Engineer

Build custom scripts to enhance websites

WebMCP Server

Turn websites into AI-accessible tools

Browsing Agent

Navigate and inspect web pages

Chat Companion

Ask questions without automation

Understanding Agents

Learn about each agent and when to use them

How It Works

The extension aggregates tools from all your open tabs and makes them available to:

The extension’s built-in agents
Local MCP clients via the native server bridge

4. Local MCP Clients

What Are Local MCP Clients?

Local MCP clients are AI assistants that run on your desktop, such as:

Claude Desktop - Anthropic’s desktop app
Claude Code - AI coding assistant
VSCode with Cline - Code editor with AI
Cursor - AI-powered code editor
Windsurf - AI development environment

Connection Methods

There are three ways to connect local MCP clients to your browser’s WebMCP tools:

Method 1: Native Server Bridge (via MCP-B)

The official MCP-B native server provides the most seamless integration.

Native Host Setup

Complete setup guide for the MCP-B native server

How it works: Quick setup:

Install native server

npm install -g @mcp-b/native-server

Start the server

@mcp-b/native-server

Configure your MCP client

Add to your MCP client config (e.g., ~/.config/claude/mcp.json):

{
  "mcpServers": {
    "webmcp": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:12306/mcp"
    }
  }
}

Best for:

Using MCP-B extension’s built-in agents
Accessing tools from multiple tabs simultaneously
Most streamlined setup

Method 2: Jason’s WebMCP Library

An alternative local server implementation by Jason McGhee that creates a direct bridge between MCP clients and websites. This is a separate implementation from the MCP-B packages.

Jason's WebMCP Library

View Jason’s WebMCP library on GitHub (separate from MCP-B)

How it works: Quick setup:

Install and configure

Run the auto-configuration script:

npx -y @jason.today/webmcp@latest --config claude

Supports: claude, cursor, cline, windsurf, or a custom path

Add widget to your website

Include Jason’s WebMCP script on your site:

<script src="webmcp.js"></script>

A widget will appear in the bottom-right corner

Connect to your site

Ask your MCP client to generate a connection token, then paste it into the widget on your website

Features:

Widget-based UI for connection management
Token-based authentication
Supports multiple websites simultaneously
Tools scoped by domain
Built-in MCP tool definer

Jason’s WebMCP is an independent implementation, separate from the MCP-B project. Both provide WebMCP functionality but with different architectures and use cases.

Best for:

Direct website-to-MCP-client connections
Website owners who want to provide WebMCP access
Users who prefer not to use browser extensions
Custom MCP client integrations

Method 3: Chrome DevTools Protocol (Coming Soon)

The MCP-B team is developing a custom Chrome DevTools Protocol (CDP) transport for connecting MCP clients directly to the browser.

Status: In development, not yet available for production use

How it will work: Advantages when available:

Direct browser connection without extension
Access to browser debugging APIs
Lower latency than HTTP bridge
More granular control over browser state

Use cases:

Advanced automation scenarios
Testing and debugging workflows
Direct browser control from MCP clients

Watch the WebMCP GitHub repository for updates on CDP transport availability.

Choosing the Right Method

Use this guide to select the best connection method for your use case:

For Website Developers
For Extension Users
For AI App Builders
For End Users

Building AI features into your site:

Use Frontend AI Frameworks (Assistant-UI, AG-UI)
Integrate WebMCP tools directly with your site’s AI
Full control over user experience

Enabling MCP client access:

Add Jason’s WebMCP widget to your site
Users can connect their local MCP clients
Provide structured tool access to visitors

Comparison Matrix

Method	Setup Complexity	Best For	Browser Extension Required	Website Changes Required
Browser Agents	None (when available)	Future-proof integration	No	No
Frontend Frameworks	Medium	Site-integrated AI	No	Yes (code integration)
MCP-B Extension	Low	Any website + built-in agents	Yes	No
Native Server (MCP-B)	Low	Multiple tabs + extension agents	Yes (MCP-B)	No
Jason’s WebMCP	Medium	Direct site-to-client	No	Yes (widget script)
CDP Transport	TBD	Advanced automation	TBD	No

Security Considerations

All connection methods execute tools with the same permissions as your browser session. Only use tools you trust and understand.

Browser Agents

Tools inherit user’s browser permissions
Origin-based security policies apply
User consent required for sensitive operations

Frontend Frameworks

Tools run in your website’s context
Same-origin policy applies
You control tool registration and execution
Validate all inputs with Zod schemas

MCP-B Extension

Extension has access to all open tabs
Tools scoped by domain
Native server listens on localhost only
Review extension security

Jason's WebMCP

Token-based authentication
Localhost-only WebSocket server
Single-use registration tokens
Website receives session token after registration
Review Jason’s WebMCP security documentation

Security Best Practices

Comprehensive security guide for WebMCP implementations

Getting Started

Ready to connect your agent? Follow these quick start guides:

Frontend Integration

Add WebMCP to your website’s AI features

MCP-B Extension

Install and use the browser extension

Native Server Setup

Connect Claude Desktop and other MCP clients

Claude Code Integration

Use WebMCP tools with Claude Code

Next Steps

Understand the architecture

Read Core Concepts to learn how WebMCP works

Review security

Check Security Best Practices before deploying

Explore examples

See working implementations in Examples

Join the community

Get help on Discord

Troubleshooting

Tools not appearing in my MCP client

Checklist:

Verify native server is running: curl http://127.0.0.1:12306/health
Check MCP-B extension is connected
Ensure website tabs with tools are open
Restart your MCP client if needed
Review troubleshooting guide

Jason's WebMCP widget not connecting

Frontend tools not being called

For frontend framework users:

Verify tools are registered: Check navigator.modelContext
Confirm MCP client is connected
Check tool schema validation
Review frontend tools guide
Enable verbose logging in your transport

Resources

Core Concepts

Understanding WebMCP architecture

Development Guide

Building WebMCP tools

API Reference

navigator.modelContext API docs

MCP Specification

Model Context Protocol docs

WebMCP GitHub

Source code and examples

Discord Community

Get help and share ideas

Getting Started

Guides

NPM Packages

Reference

​Overview

​Connection Methods

Browser Agents

Frontend AI Frameworks

MCP-B Extension

Local MCP Clients

​1. Browser Agents (Native Support)

​What Are Browser Agents?

​Current Status

​How It Works

​Getting Ready

​2. Frontend AI Frameworks

​What Are Frontend AI Frameworks?

Frontend Tool Calling Guide

​Supported Frameworks

Assistant-UI

AG-UI

​How It Works

​Quick Example

​3. MCP-B Extension

​What Is the MCP-B Extension?

Extension Guide

​Built-in Agents

Userscript Engineer

WebMCP Server

Browsing Agent

Chat Companion

Understanding Agents

​How It Works

​4. Local MCP Clients

​What Are Local MCP Clients?

​Connection Methods

​Method 1: Native Server Bridge (via MCP-B)

Native Host Setup

​Method 2: Jason’s WebMCP Library

Jason's WebMCP Library

​Method 3: Chrome DevTools Protocol (Coming Soon)

​Choosing the Right Method

​Comparison Matrix

​Security Considerations

Security Best Practices

​Getting Started

Frontend Integration

MCP-B Extension

Native Server Setup

Claude Code Integration

​Next Steps

​Troubleshooting

​Resources

Core Concepts

Development Guide

API Reference

MCP Specification

WebMCP GitHub

Discord Community

Overview

Connection Methods

1. Browser Agents (Native Support)

What Are Browser Agents?

Current Status

How It Works

Getting Ready

2. Frontend AI Frameworks

What Are Frontend AI Frameworks?

Supported Frameworks

How It Works

Quick Example

3. MCP-B Extension

What Is the MCP-B Extension?

Built-in Agents

How It Works

4. Local MCP Clients

What Are Local MCP Clients?

Connection Methods

Method 1: Native Server Bridge (via MCP-B)

Method 2: Jason’s WebMCP Library

Method 3: Chrome DevTools Protocol (Coming Soon)

Choosing the Right Method

Comparison Matrix

Security Considerations

Getting Started

Next Steps

Troubleshooting

Resources