core

Enable AI agents to control frontend web apps directly via MCP. Expose your application's state, actions, and UIs as MCP tools and MCP apps that AI can understand and invoke.

Documentation · Get Started · Demos

MCP-Web makes the frontend the main control surface for both humans and AI, ensuring human-AI parity. You can automate clicks with natural language and take over with direct interaction at any time.

Key Features

• 🛠️ Dynamically expose state and actions as type-safe MCP tools
• ✨ Auto-generate efficient tools from schemas with built-in helpers
• 📊 Build visual tools from components with MCP Apps that render UI inline in AI chat
• 🔄 Trigger AI queries from your frontend using the same tools
• 🪟 Interact with multiple browser sessions independently
• 🎯 Works with any framework: React, Vue, Svelte, vanilla JS

Quick Start

1. Add to Your Frontend

npm install @mcp-web/core

import { MCPWeb } from '@mcp-web/core';
import { z } from 'zod';

const mcp = new MCPWeb({ name: 'My App', autoConnect: true });

// Add a simple tool
mcp.addTool({
  name: 'get_greeting',
  description: 'Get a personalized greeting',
  handler: ({ name }) => ({ message: `Hello, ${name}!` }),
  inputSchema: z.object({ name: z.string() }),
});

// Or expose state with auto-generated getter/setter tools
let counter = 0;
mcp.addStateTools({
  name: 'counter',
  description: 'A counter value',
  get: () => counter,
  set: (value) => { counter = value; },
  schema: z.number(),
});
// Creates: get_counter() and set_counter({ value })

2. Run the Bridge

npx @mcp-web/bridge
# Runs WebSocket and MCP HTTP server on :3001

3. Connect Your AI Agent

You have two options to connect an MCP-compatible AI agent to the bridge.

Option 1: Remote MCP (Recommended)

The simplest approach is to connect directly via URL. Get the config from your frontend:

console.log(JSON.stringify(mcp.remoteMcpConfig, null, 2));

{
  "mcpServers": {
    "my-app": {
      "url": "https://localhost:3001?token=your-auth-token"
    }
  }
}

In Claude Desktop, add this via Settings > Connectors > Add Custom Connector.

Option 2: Local MCP Client

Alternatively, use @mcp-web/client as a local STDIO transport. Get the config from your frontend:

console.log(JSON.stringify(mcp.mcpConfig, null, 2));

{
  "mcpServers": {
    "my-app": {
      "command": "npx",
      "args": ["@mcp-web/client"],
      "env": {
        "MCP_SERVER_URL": "http://localhost:3002",
        "AUTH_TOKEN": "your-auth-token"
      }
    }
  }
}

Add this to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

[!NOTE] Note, our client is also the best option for local development.

How It Works

With MCP-Web, your frontend becomes the main control surface for both humans and AI. Humans control state through the UI while AI controls the same state through MCP tools.

This design makes human-AI parity straightforward: both have the same capabilities, so you can automate tasks with natural language and take over with direct interaction whenever you want.

Frontend App  ↔  @mcp-web/core  ↔  @mcp-web/bridge  ↔  AI App/Agent
         ╰─ runs ─╯       ╰── WS/SSE ──╯     ╰─ Remote MCP ─╯

On a technical level, your frontend registers tools with core, which connects to the bridge server. AI agents connect to the bridge directly via Remote MCP (recommended), or through a local client via STDIO.

Packages

Learn More

• Get Started Guide - Full setup walkthrough
• Visual Tools - Build MCP Apps that render UI in AI chat
• Architecture - How the pieces fit together
• API Reference - Complete API documentation
• Todo Demo - Full CRUD example

License

Apache License 2.0