npm package: @mcp-use/webmcp
Description: Embed any MCP server on your website — WebMCP proxy + live inspector overlay
Author: mcp-use, Inc.
Latest version: 0.1.0

# @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

```bash
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.

```html
<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

```tsx
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

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

```bash
# 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:

```tsx
<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

```ts
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

```tsx
<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.

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

### `<WebMCPInspector>` — inspector only

Mount the overlay connected to any MCP server URL.

```tsx
<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