webmcp-connect

webmcp-connect

Connect any MCP server to the browser via the WebMCP API.

Three lines. That's it.

import { WebMCP } from 'webmcp-connect';

const mcp = new WebMCP('https://mcp.example.com/sse');
await mcp.connect();
// Done. Tools are auto-registered with the browser's AI.

npm install webmcp-connect

Why?

MCP servers are everywhere — GitHub, Slack, databases, you name it. But they're trapped behind desktop clients and CLI tools.

Why should using an MCP tool require Cursor or Claude Desktop?

webmcp-connect gives any webpage access to any MCP server. The browser becomes the agent surface.

Examples

Connect to a GitHub MCP server

import { WebMCP } from 'webmcp-connect';

const github = new WebMCP('https://mcp-github.example.com/sse');
github.setAuth({ type: 'bearer', token: 'ghp_...' });

const { tools } = await github.connect();
console.log(tools.map(t => t.name));
// ['create_issue', 'search_repos', 'get_file_contents', ...]

github.register();  // or let autoRegister handle it
// The AI can now create issues, search repos, read files

Enrich every tool call with page context

const mcp = new WebMCP('https://mcp.example.com/sse', {
  enrichContext: (toolName, args) => ({
    ...args,
    page_url: location.href,
    page_title: document.title,
    selected_text: window.getSelection().toString(),
  }),
});

await mcp.connect();
// Every tool call now carries page context — the AI knows what you're looking at

Audit every tool call

const mcp = new WebMCP('https://mcp.example.com/sse', {
  onToolCall: (name, args) => {
    analytics.track('mcp_tool_call', { tool: name, args });
  },
  onResponse: (name, result) => {
    console.log(`[${name}]`, result);
    return result;
  },
  onError: (name, err) => {
    Sentry.captureException(err, { extra: { tool: name } });
  },
});

Mix remote + local tools

await mcp.connect();

mcp.register([
  {
    name: 'get_selection',
    description: 'Get the currently selected text on the page',
    inputSchema: { type: 'object', properties: {} },
    execute: async () => ({
      content: [{ type: 'text', text: window.getSelection().toString() }],
    }),
  },
  {
    name: 'get_page_html',
    description: 'Get the full HTML of the current page',
    inputSchema: { type: 'object', properties: {} },
    execute: async () => ({
      content: [{ type: 'text', text: document.documentElement.outerHTML }],
    }),
  },
]);
// Remote MCP tools + page-local tools, all registered together

Call tools directly (no WebMCP needed)

const mcp = new WebMCP('https://mcp.example.com/sse');
await mcp.connect();

// Use tools programmatically — works without navigator.modelContext
const result = await mcp.callTool('search', { query: 'webmcp' });
console.log(result.content[0].text);

Custom headers

const mcp = new WebMCP('https://mcp.example.com/sse', {
  headers: {
    'X-Tenant-ID': 'acme-corp',
    'Authorization': 'Bearer sk-...',
  },
});

Headers are merged into every request. setAuth() headers go first, custom headers override.

API

new WebMCP(serverUrl, options?)

Option	Type	Description
autoRegister	boolean	Auto-register tools on connect (default: true)
headers	object	Custom headers merged into every request
enrichContext	(name, args) => args	Enrich tool args before proxying
onToolCall	(name, args) => void	Called before each tool call
onResponse	(name, result) => result	Transform responses
onError	(name, error) => void	Error handler
logger	object	Custom logger (default: console)

Methods

Method	Returns	Description
connect()	{ tools, prompts, resources }	Initialize + discover
register(extraTools?)	tool[]	Register with WebMCP
callTool(name, args)	result	Call a tool
getPrompt(name, args)	result	Get a prompt
readResource(uri)	result	Read a resource
setAuth({ type, token })	—	Set auth (bearer, apikey, basic)
disconnect()	—	Clear context + logout

CORS

This module runs in the browser, so the MCP server must allow cross-origin requests. If you control the server, add Access-Control-Allow-Origin headers. Most MCP SDKs support this out of the box.

No CORS = the browser blocks the request before it reaches your code. That's a browser security feature, not a bug.

Requirements

• A browser with WebMCP support
• connect() and callTool() work without WebMCP — you just can't register()

License

MIT