MCP-FE MCP Server

MCP-FE (Model Context Protocol - Frontend Edge)

MCP-FE turns the browser runtime into an active, queryable node in the MCP ecosystem. Instead of continuously pushing analytics-style data, your frontend exposes on-demand MCP tools so an AI agent can ask questions about what just happened and what the UI state is right now.

It bridges the gap between AI agents (e.g., Claude or Cursor) and the real-time state of your frontend application using:

• a browser worker (SharedWorker / ServiceWorker) that stores events and routes tool calls,
• a Node.js proxy that exposes an MCP endpoint to remote agents, and
• native WebMCP support — when the browser implements navigator.modelContext, tools are automatically registered with the browser's built-in agent system too.

Why MCP-FE?

AI agents are often runtime-blind: they can read your code, but they can’t see the current DOM, the state of a Redux/Zustand store, or the exact interaction sequence that led to an error.

MCP-FE exposes the browser runtime as a first-class MCP Server so that context is retrievable on demand via tool calls.

⚠️ Project Status: Experimental (PoC)

This project is currently a Proof of Concept. While the architecture is stable and demonstrates the power of MCP-FE, it is not yet intended for high-stakes production environments.

Current focus:

• Finalizing the SharedWorker/ServiceWorker fallback logic.
• Refining the React hook lifecycle (auto-deregistration of tools).
• Hardening the Proxy-to-Worker authentication flow.

See the security roadmap section below for more details.

Quick Start (Local Live Demo)

This monorepo includes a small demo frontend app and the MCP proxy. Run the commands below to start a local live demo on your machine.

1. Install dependencies

pnpm install

2. Start the demo app + MCP Proxy

pnpm start

3. Open the demo frontend

Navigate to http://localhost:4200 (or the port shown in your terminal). The browser worker will automatically register and connect.

4. Connect an AI agent

Point your MCP-compatible agent to:

• MCP endpoint (HTTP): http://localhost:3001/mcp

Note: the example app connects the worker to the proxy via WebSocket (e.g., ws://localhost:3001).

How It Works

Traditional MCP integrations are backend-centric. Frontends usually push events continuously, whether anyone needs them or not.

MCP-FE inverts the flow:

• Pull, not push: the frontend does not stream context by default.
• Worker-based edge: a browser SharedWorker (preferred) or ServiceWorker stores event history (IndexedDB) and coordinates tool calls.
• Proxy for remote agents: a Node.js proxy maintains a WebSocket connection to the worker and exposes MCP tools to agents.
• Dynamic tools: register tools from application code; handlers run in the main thread with controlled access to state/DOM/imports.

sequenceDiagram
participant A as 🤖 AI Agent (Claude/Cursor)
participant P as 🖥️ Node.js MCP Proxy
participant W as ⚙️ Shared/Service Worker
participant M as 🌐 Main Thread (App)

    Note over A, M: The Pull Model: Context is retrieved only on demand

    A->>P: Call tool (e.g., 'get_react_state')
    P->>W: Forward call via WebSocket
    W->>M: Request data from registered handler
    
    Note right of M: Handler accesses React State, DOM, or LocalStorage
    
    M-->>W: Return serializable state/data
    W-->>P: Send JSON-RPC response
    P-->>A: Tool result (JSON)
    
    Note over A: Agent now "sees" the UI runtime

Key Concepts

MCP Workers: SharedWorker vs ServiceWorker

• SharedWorker (preferred):

  • One shared instance is available to all same-origin windows/iframes.
  • Good for multi-tab apps and when you want a single MCP edge connection per browser.

• ServiceWorker (fallback):

  • Runs in background, lifecycle managed by the browser.
  • Useful when SharedWorker is not supported.

WorkerClient in this repo prefers SharedWorker and automatically falls back to ServiceWorker. It also supports passing an explicit ServiceWorkerRegistration to use a previously registered service worker.

Worker as an MCP Edge Server

The Shared/Service Worker acts as a lightweight edge node that enables you to:

• Collect UI-level event history (navigation, interactions, errors)
• Store events in IndexedDB for later retrieval
• Expose data and actions via MCP tools
• Maintain a persisten