DOCSEARCHbyAlgolia
Submit Docs

WebMCP Documentation

repository·main·Indexed 20 days ago

https://github.com/jasonjmcghee/webmcp

A WebSocket-based Model Context Protocol (MCP) implementation that allows websites to act as MCP servers. It enables websites to expose tools, resources, and prompts to client-side LLMs via a local WebSocket bridge, supporting integration with MCP clients like Claude, Cursor, Cline, and Windsurf.

Tokens
6.1K
Snippets
22
Records
33
Agent score
72%

What's inside WebMCP

  1. How WebMCP works (Architecture)

    main

    WebMCP acts as a bridge between an MCP client and a website using a localhost-only WebSocket server. This prevents external access while allowing your local browser to communicate with your local MCP client.

    The Request Flow:

    1. MCP Client sends a request to the MCP Server.
    2. MCP Server forwards the request to the WebSocket Server.
    3. WebSocket Server forwards the request to the Web Page.
    4. The Web Page executes the tool/resource and sends the result back through the same path.

    Key Concepts:

    • Scoping: Tools are scoped by domain name to prevent collisions.
    • Unified List: The MCP client sees all tools from all connected websites as a single list, using channel prefixes to keep them organized.
    • Security: Authentication is handled via a registration token exchange. Once a website registers, the token is deleted.

  2. How to connect an LLM to a WebMCP-enabled website

    main

    Once WebMCP is running in your MCP client, follow these steps to connect to a website:

    1. Generate a token: Ask your LLM to generate an MCP token (or run npx @jason.today/webmcp --new manually to avoid the model seeing the token).
    2. Register the website: Copy the generated token and paste it into the input field on the WebMCP-enabled website.
    3. Automatic connection: The website will register, the token will be discarded, and the website will receive a session token to begin communicating tools/resources to your LLM.

    To disconnect, you can click "disconnect" on the website, close the browser tab, or shut down the server using npx @jason.today/webmcp -q.

  3. Run WebMCP using Docker

    main
    You can dockerize the WebSocket server. If you provide the --docker flag to your MCP client configuration alongside --mcp, the client will assume the server is running in a Docker container and connect via WebSockets. Websites will also communicate with this Docker container.

  5. Install WebMCP for use with an MCP client

    main

    To use WebMCP with an existing MCP client (like Claude, Cursor, Cline, or Windsurf), use npx to install and configure it automatically. You must specify your client name in the --config flag.

    Note: Some clients, such as Claude Desktop, may require a restart to recognize new tools after installation.

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

  6. Integrate WebMCP with an MCP client

    main

    To use WebMCP as an MCP server, add the following command to your MCP client configuration:

    npx @jason.today/webmcp --mcp

    npx @jason.today/webmcp --mcp

  7. Add WebMCP support to your website

    main

    To allow your website to share tools, resources, and prompts with client-side LLMs, include the webmcp.js script in your page. The WebMCP widget will automatically initialize and appear in the bottom right corner of the page.

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

  8. How WebMCP handles tool calls

    main

    When a server requests a tool execution via a callTool message, the WebMCP client identifies the tool by its name from the availableTools registry. The client then executes the tool's execute(args) method, where args are the arguments provided by the server.

    WebMCP supports both synchronous and asynchronous tool execution. If the execute method returns a Promise, the client waits for resolution before sending a toolResponse message back to the server. If the promise rejects, an error message is sent. If the execution is synchronous, the result is sent immediately. If the tool is not found in the registry, the client responds with a toolResponse containing an error: Tool not found: <tool_name>.

  9. How WebMCP handles prompt requests

    main

    The client responds to getPrompt messages from the server by looking up the requested prompt name in the availablePrompts registry.

    Upon finding a match, the client calls the prompt's execute(args) method. Similar to tools, prompts can be synchronous or asynchronous (returning a Promise). The result (or error) is then wrapped in a promptResponse message and sent back to the server. If the prompt name does not exist, the client sends a promptResponse with the error: Prompt not found: <name>.

  10. How WebMCP bridges MCP and WebSockets

    main

    WebMCP acts as a bridge between the Model Context Protocol (MCP) and a WebSocket-based web environment.

    1. MCP Interface: The server exposes standard MCP capabilities (Tools, Prompts, Resources, and Sampling) via stdio transport. This allows LLM clients (like Claude Desktop) to interact with it.
    2. WebSocket Bridge: When an MCP client calls a tool, prompt, or resource, the server translates that request into a JSON message and sends it over a WebSocket connection to a specific path (/mcp) on the WebMCP website.
    3. Request/Response Mapping: Because WebSockets are asynchronous, the server maintains a pendingRequests map. It assigns a unique requestId to every outgoing WebSocket message and waits for a corresponding response message from the website containing the same ID before resolving the original MCP request.
    4. Capabilities: The server supports listChanged notifications for tools, prompts, and resources, as well as subscribe for resources and sampling for LLM-driven requests.

  11. How WebMCP handles resource requests

    main

    When the server sends a readResource message with a specific uri, the client attempts to find a matching resource handler in the availableResources registry using two strategies:

    1. Direct Match: It looks for a non-template resource where resource.uri === uri.
    2. Template Match: If no direct match is found, it looks for a template resource (isTemplate: true) where the uri starts with the uriTemplate prefix (the part of the template before the first { character).

    Once a handler is found, the client calls resourceObj.provide(uri). The result (or error) is sent back to the server via a resourceResponse message. If no handler is found, the client responds with a resourceResponse containing the error: No resource handler found for URI: <uri>.

  12. Understand the WebMCP WebSocket communication model

    main

    WebMCP uses a WebSocket-based client-server architecture organized into channels.

    • Channels: Each WebSocket connection is assigned a channel based on its URL path (e.g., /my-channel). Clients in the same channel can communicate, and the server manages registries of tools, prompts, and resources for each channel.
    • MCP Path: A special reserved path (/mcp) used by Model Context Protocol (MCP) clients. MCP clients see a unified view of all tools, prompts, and resources across all channels, with names prefixed by their original channel path (e.g., my-channel-toolName).
    • Registration Path: A special path (/register) used to establish new channels. A client connects to /register, sends a base64-encoded JSON payload containing a host and a token, and upon success, receives a sessionToken and is expected to reconnect to the newly created channel path.
    • Routing: The server acts as a router. When an MCP client calls a tool, the server identifies the target channel and forwards the request to an available client connected to that channel.