WebMCP Example

About WebMCP

WebMCP is an open source JavaScript library that allows any website to integrate with the Model Context Protocol. It provides a small blue widget in the bottom right corner of your page that allows users to connect to and interact with your webpage via LLM or agent.

Connect to this site (or any site that uses WebMCP)

To use the WebMCP features on a website, you need to:

1. Make sure you have an MCP Client and configure it

For example, you can get Claude Desktop, and configure it by going to Settings > Developer > Edit Config, and add MCP server to your configuration

{
  "mcpServers": {
    "webmcp": {
      "command": "npx",
      "args": [\
        "-y",\
        "@jason.today/webmcp@latest",\
        "--mcp"\
      ]
    }
  }
}

4. Start your MCP client and ask it to make a webmcp token
5. Click the blue square in the corner and paste the token
6. If you're using Claude Desktop and/or don't see tools immediately appear, restart your MCP client. (hopefully all MCP client will support tool changes soon!)

Getting Started (for website developers)

To use WebMCP, simply include the script on your page:

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

The WebMCP widget will automatically initialize and appear in the bottom right corner of your page.

MCP Features

Registering Tools

Tools allow the LLM to perform actions on your website. They are registered via calling registerTool.

// Initialize with custom options
const mcp = new WebMCP({
    color: '#4CAF50',
    position: 'top-right',
    size: '40px',
    padding: '15px'
});

// Register custom tools
mcp.registerTool(
    'weather',
    'Get weather information',
    {
        location: { type: "string" }
    },
    function(args) {
        return {
            content: [{\
                type: "text",\
                text: `Weather for ${args.location}: Sunny, 22°C`\
            }]
        };
    }
);

To provide the best experience for users, it is recommended to register all tools directly after loading <script src="webmcp.js"></script>, as MCP clients may need to be restarted to get the available tools.

Registering Prompts

Prompts are predefined templates that clients can use for LLM interactions. They allow standardization of common queries and can accept dynamic arguments.

// Register a prompt for generating a Git commit message
mcp.registerPrompt(
    'git-commit',
    'Generate a Git commit message',
    [\
        {\
            name: 'changes',\
            description: 'Git diff or description of changes',\
            required: true\
        }\
    ],
    function(args) {
        return {
            messages: [\
                {\
                    role: "user",\
                    content: {\
                        type: "text",\
                        text: `Generate a concise but descriptive commit message for these changes:\n\n${args.changes}`\
                    }\
                }\
            ]
        };
    }
);

Registering Resources

Resources expose data and content that can be read by clients and used as context for LLM interactions. Resources are identified by URIs and can contain either text or binary data.

// Register a resource for a specific file
mcp.registerResource(
    'page-content',
    'Current page content',
    {
        uri: 'page://current',
        mimeType: 'text/html'
    },
    function(uri) {
        return {
            contents: [\
                {\
                    uri: uri,\
                    mimeType: 'text/html',\
                    text: document.body.innerHTML\
                }\
            ]
        };
    }
);

Sampling with WebMCP

Sampling allows servers to request LLM completions through the client. This enables sophisticated agentic behaviors while maintaining security and privacy via human oversight.

When a sampling request is received, WebMCP displays a modal dialog asking the user to provide a response:

// Sampling is handled automatically by WebMCP
// The server sends a sampling request:
{
  "method": "sampling/createMessage",
  "params": {
    "messages": [\
      {\
        "role": "user",
        "content": {\
          "type": "text",
          "text": "Write the appropriate DuckDB SQL to get the list of users joined with their accounts"\
        }\
      }\
    ],
    "systemPrompt": "You are a helpful assistant.",
    "includeContext": "thisServer",
    "maxTokens": 100
  }
}
// The WebMCP widget shows a dialog to the user, who can then type a response
// The response is sent back to the server