WebMCP Proxy

Advertise your existing MCP server's tools via WebMCP on your website so any browsing agent can use them.

WebMCP Proxy connects to a remote MCP server, discovers its tools, and registers them with the browser's document.modelContext API. When a browsing agent invokes a tool, the call is proxied to your MCP server and the result forwarded back.

Installation

npm install webmcp-proxy

Usage

Vanilla JS

import { createWebMcpProxy } from "webmcp-proxy";

const proxy = await createWebMcpProxy({
  url: "https://mcp.example.com/mcp",
});

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

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

React

import { WebMCPProxy } from "webmcp-proxy/react";

export default function App() {
  return (
    <>
      <WebMCPProxy url="https://mcp.example.com/mcp" />
      {/* Your app content */}
    </>
  );
}

Vue

<script setup>
import { WebMCPProxy } from "webmcp-proxy/vue";
</script>

<template>
  <WebMCPProxy url="https://mcp.example.com/mcp" />
  <!-- Your app content -->
</template>

Options

All variants accept the same core options:

Option	Type	Required	Description
url	string	Yes	URL of the remote MCP server
headers	Record<string, string>	No	Additional headers sent with every request (e.g. Authorization)

How it works

sequenceDiagram
    participant Page as Your Page
    participant Proxy as webmcp-proxy
    participant MCP as Remote MCP Server
    participant Agent as Browsing Agent

    Page->>Proxy: createWebMcpProxy({ url })

    rect rgb(240, 240, 240)
        note right of Proxy: Streamable HTTP, fallback to SSE
        Proxy->>MCP: initialize
        MCP-->>Proxy: capabilities
        Proxy->>MCP: tools/list
        MCP-->>Proxy: available tools
    end

    loop For each tool
        Proxy->>Page: document.modelContext.registerTool()
    end

    Agent->>Page: Discovers tools via WebMCP
    Agent->>Page: Calls a tool
    Page->>Proxy: execute(args)
    Proxy->>MCP: tools/call
    MCP-->>Proxy: result
    Proxy-->>Page: result
    Page-->>Agent: result

Loading

Starting in Chrome 153, each tool's execute callback receives an AbortSignal as execute(input, { signal }). The proxy forwards that signal to the remote MCP tools/call, so cancelled agent/user executions abort the in-flight request instead of leaving work running.

Coexistence with page-specific tools

WebMCP Proxy uses registerTool rather than provideContext to manage tools. This means it will not overwrite other tools the page registers on its own — as long as those also use registerTool. Proxy tools and page-local tools coexist safely side by side.

Tool unregistration is handled via AbortSignal (the recommended approach starting from Chrome 148). For backward compatibility with older browsers, unregisterTool() is also called when available. As of Chrome 153, unregistering a tool no longer cancels in-flight executions — cancellation goes through the per-execution signal instead.

Demo

A live demo is hosted at webmcp.netlify.app.

The demo/ folder contains a standalone React + Vite app that lets you enter an MCP server URL, connect to it, and see the tools it exposes — all registered via WebMCP in the browser.

To run the demo locally:

pnpm run demo

This starts the Vite dev server with a built-in CORS proxy so you can connect to any MCP server without cross-origin issues.

Requirements

• The remote MCP server must support Streamable HTTP or SSE transport
• The MCP server must allow CORS requests from the browser origin
• The browser must support the WebMCP API (document.modelContext, with a fallback to the deprecated navigator.modelContext) — if unavailable, the proxy logs a warning and becomes a no-op

License

ISC