@mcp-fe/react-tools

AI agents are oftenruntime-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 thebrowser runtimeas a first-class MCP Server so that context is retrievableon demandvia tool calls.

-

In-app AI copilot— give users an AI assistant that truly understands your application. Because tools return structured component data rather than pixels or DOM nodes, the agent works reliably even as your UI evolves. "Book the cheapest Tuesday flight" or "fill the form with my usual details" — the agent reads live state and triggers actions directly, no browser extension required.

Support with full context— when a user opens a support chat, the agent immediately queriesget_form_stateorget_validation_errorsinstead of asking for screenshots. It sees exactly what the user sees — active errors, current field values, where they are in a flow — and resolves issues in seconds rather than back-and-forth exchanges.

Guided complex workflows— in tax forms, insurance claims, or ERP systems, users often get lost in deep menus and multi-step flows. The agent knows exactly which step they're on, what's already filled, and what's missing — and can navigate or configure the UI on their behalf instead of pointing them to documentation.

Ready for the browser AI era— as AI browser extensions and built-in browser agents become mainstream, apps with MCP-FE are already compatible. Via the WebMCP adapter, the browser's native agent gets structured semantic tools throughnavigator.modelContextinstead of scraping the DOM. OneregisterTool()call covers both today's remote agents and tomorrow's browser-native ones.

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

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

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

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

Runtime flow — how a tool call travels from agent to browser and back.

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

- Pull, not push:the frontend doesnotstream context by default.
- Worker-based edge:a browserSharedWorker(preferred) orServiceWorkerstores 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, <br/>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

MCP Workers: SharedWorker vs ServiceWorker

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

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

WorkerClientprefers SharedWorker and automatically falls back to ServiceWorker. It also supports passing an explicitServiceWorkerRegistrationto use a previously registered service worker.

The Shared/Service Worker acts as a lightweightedge nodethat enables you to:

- CollectUI-level event history (navigation, interactions, errors)
- Storeevents in IndexedDB for later retrieval
- Exposedata and actions via MCP tools
- Maintaina persistent WebSocket connection to the proxy
- Registercustom tools dynamically with handlers running in the main thread (full browser API access)

The MCP workernever sends context proactively to the backend. Context is sharedonlywhen an AI agent explicitly requests it by calling a tool.

Your App ──→ workerClient.registerTool('my-tool', ...) │ ├── ① Worker transport ──→ Proxy ──→ Remote AI agents (Claude, Cursor, ...) │ └── ② WebMCP adapter ──→ navigator.modelContext.registerTool() └──→ Browser's built-in agent / extensions

OneregisterTool()call → two delivery channels.Your tool handlers are written once and automatically served to both remote agents (via WebSocket + MCP proxy) and the browser's native agent system (vianavigator.modelContext).

WebMCP isauto-detected— if the browser supportsnavigator.modelContext, tools are registered there automatically. No configuration needed:

Unlike traditional analytics or logging tools that stream data to third-party servers,MCP-FE is passive and restrictive:

- Explicit Exposure Only: The AI agent haszero "magic" accessto your app. It can only see data or trigger actions that you explicitly expose viaregisterTooloruseMCPTool.
- Zero-Stream Policy: No data is ever pushed automatically. Context transfer only happens when an AI agent triggers a specific tool call.
- Local Execution: Tool handlers run in your application's context, allowing you to implement custom authorization, filtering, or scrubbing before returning data to the agent.
- Privacy First: Sensitive fields (PII, passwords, tokens) never leave the client unless the developer intentionally includes them in a tool's return payload.

Component overview — the three layers that make up MCP-FE.

The MCP-FE architecture is built on three core layers designed to keep the main application thread responsive while providing a persistent link to AI agents.

The Proxy acts as the gateway. It speaks the standardMCP Protocoltowards the AI agent (via HTTP/SSE) and maintains a persistentWebSocketconnection to the browser.

- Role: Bridges the gap between the internet and the user's local browser session.
- Security: Handles Bearer token authentication to ensure only authorized agents can talk to the worker.

2. The MCP Worker (SharedWorker / ServiceWorker)

This is the "Brain" on the Frontend Edge. It runs in its own thread, meaning it doesn't slow down your UI.

- Event Logging: Automatically captures interactions and errors intoIndexedDB.
- Routing: When a tool call comes from the Agent, the Worker routes it to the correct tab or the Main Thread.
- Resilience: Implements aPing-Pong mechanismto keep the WebSocket alive even when the user isn't actively interacting with the page.

This is where your React/Vue/JS code lives.

- Dynamic Tools: Using hooks likeuseMCPTool, your components register handlers that have direct access to the liveDOM, State, and LocalStorage.
- Zero-Push: It only executes logic and sends data when the Worker explicitly asks for it (the Pull Model).

Michal Kopecký— Frontend engineer & creator of MCP-FE

I built MCP-FE to solve the "runtime-blindness" of current AI agents. By treating the browser as an active edge-node, we can provide agents with deep, real-time context without sacrificing user privacy or network performance.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Create crafted UI components inspired by the best 21st.dev design engineers.

Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server

An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .

MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent

ALAPI MCP Tools,Call hundreds of API interfaces via MCP

AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform

MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.