@mcp-use/webmcp

Embed any MCP server on your website — WebMCP proxy + live inspector overlay.

Drop one script tag (or one React component) into your page and get:

1. WebMCP Proxy — your remote MCP server's tools are registered with navigator.modelContext so any browsing agent on the page can discover and call them.
2. Aggregating Page Server — an optional Service Worker that merges the remote server's primitives with any other tools registered on navigator.modelContext into a single unified MCP server.
3. Inspector Overlay — a collapsible floating panel (right side of page, bottom sheet on mobile) powered by the @mcp-use/inspector, showing tools, resources, prompts, and a chat interface — all in one place.

Installation

npm install @mcp-use/webmcp
# or
pnpm add @mcp-use/webmcp

Quick start

CDN — zero config

Add to any HTML page. No build step required.

<script
  type="module"
  src="https://cdn.mcp-use.com/webmcp/latest/webmcp.js"
  data-mcp-url="https://your-server.com/mcp"
></script>

The script auto-detects the data-mcp-url attribute and initialises everything.

React

import { WebMCP } from "@mcp-use/webmcp/react";

export default function App() {
  return (
    <>
      <WebMCP url="https://your-server.com/mcp" />
      {/* rest of your app */}
    </>
  );
}

Vanilla JS

import { createWebMcp } from "@mcp-use/webmcp";

const instance = await createWebMcp({
  url: "https://your-server.com/mcp",
});

console.log("Registered tools:", instance.tools);

// Later, to clean up:
await instance.disconnect();

How it works

Your Page
  │
  ├── WebMCP Proxy (McpConnection)
  │     ├── Connects to remote MCP server (Streamable HTTP / SSE)
  │     ├── Registers every tool with navigator.modelContext.registerTool()
  │     └── Browsing agents discover & call tools via navigator.modelContext
  │
  ├── Aggregating Service Worker  (/webmcp-page-server)
  │     ├── tools/list  → merges remote tools + navigator.modelContext.listTools()
  │     ├── tools/call  → routes to remote server or navigator.modelContext.executeTool()
  │     ├── resources/* → forwarded to remote server
  │     └── prompts/*   → forwarded to remote server
  │
  └── Inspector Overlay  (React, fixed right / bottom-sheet on mobile)
        └── McpClientProvider → /webmcp-page-server (aggregated single server)
              ├── Tools tab    — remote + page tools merged
              ├── Resources tab
              ├── Prompts tab
              ├── Chat tab     — LLM chat with full tool access
              └── Page tab     — live navigator.modelContext snapshot

Aggregating Service Worker (recommended)

For the inspector to show a single merged view of remote + page tools, serve the Service Worker file from your origin:

# Copy the pre-built SW to your public directory
cp node_modules/@mcp-use/webmcp/dist/webmcp-sw.js public/webmcp-sw.js

The SW is automatically registered at /webmcp-sw.js. You can override the path:

<WebMCP url="https://your-server.com/mcp" swPath="/static/webmcp-sw.js" />

If the SW is not available the inspector falls back to connecting directly to the remote server.

API reference

createWebMcp(options) — vanilla JS

const instance = await createWebMcp(options);

| Option | Type | Default | Description | |---|---|---|---| | url | string | required | Remote MCP server URL | | headers | Record<string,string> | — | Extra request headers (e.g. Authorization) | | inspector | boolean \| object | true | Inspector overlay config — false disables it | | inspector.name | string | "MCP" | Display name in the panel header | | swPath | string | "/webmcp-sw.js" | Path to the aggregating SW script | | usePageServer | boolean | true | Whether to attempt SW registration |

Returns a WebMcpInstance:

| Property | Type | Description | |---|---|---| | tools | Tool[] | Tools discovered from the remote server | | inspectorServerUrl | string | URL the inspector is connected to | | disconnect() | () => Promise<void> | Clean up everything |

<WebMCP> — full experience

<WebMCP
  url="https://your-server.com/mcp"
  headers={{ Authorization: "Bearer token" }}
  name="My Server"
  swPath="/webmcp-sw.js"
  onReady={(instance) => console.log(instance.tools)}
  onError={(err) => console.error(err)}
/>

<WebMCPProxy> — proxy only

Registers tools with navigator.modelContext, no inspector UI.

<WebMCPProxy url="https://your-server.com/mcp" />

<WebMCPInspector> — inspector only

Mount the overlay connected to any MCP server URL.

<WebMCPInspector
  serverUrl="https://your-server.com/mcp"
  name="My Server"
  defaultOpen
/>

CDN script attributes

| Attribute | Description | |---|---| | data-mcp-url | Remote MCP server URL (required) | | data-name | Display name (default: "MCP") | | data-sw-path | Path to SW script (default: "/webmcp-sw.js") | | data-no-page-server | "true" to skip SW registration | | data-no-inspector | "true" for proxy-only mode | | data-header-* | Extra request headers, e.g. data-header-authorization="Bearer token" |

Requirements

• The remote MCP server must support Streamable HTTP or SSE transport.
• The MCP server must allow CORS requests from your page origin.
• The inspector overlay requires React 18 or 19 (included when using the React component; bundled in the CDN build).
• The aggregating Service Worker requires the webmcp-sw.js file to be served from your domain (same origin as the page).

License

MIT