Frontendmcp

Overview

The Model Context Protocol (MCP) allows applications to provide context and tools to LLMs in a standardized way. FrontendMCP extends this model to browser environments.

This FrontendMCP provides a lightweight relay and transport layer that allows MCP servers to run in client-side applications while remaining accessible to backend LLMs and other MCP clients.

This is particularly useful when the capabilities you want to expose only exist in the client: local state, browser-only APIs, UI logic or frontend code that makes authenticated backend requests on behalf of the current user.

A prehosted relay server is available, so you can get started with FrontendMCP in just a few lines of code. Server implementations in Rust and TypeScript are also provided for those who want to self-host or customize their relay server.

Installation

npm install frontendmcp zod

Usage

import { FrontendMCPServer } from 'frontendmcp';
import { z } from 'zod';

const mcp = new FrontendMCPServer({
	name: 'ClientTools',
	version: '1.0',
	frontendMCP: {
		// Optional structured WebSocket lifecycle and JSON-RPC frame tracing.
		// Authentication tokens are never included in trace events.
		trace: true
	}
});

mcp.registerTool(
	'get_selection',
	{
		description: 'Read highlighted text',
		inputSchema: z.object({})
	},
	async () => ({
		content: [
			{
				type: 'text',
				text: window.getSelection()?.toString() || ''
			}
		]
	})
);

mcp.connect();

// Pass the server's URL to your backend LLM or MCP client to start using the tool
const url = mcp.url;

connect() resolves only after the relay WebSocket is open and its authentication packet has been sent. Startup failures reject the returned promise, so applications should await it:

try {
	await mcp.connect();
	console.log('FrontendMCP is connected');
} catch (error) {
	console.error('FrontendMCP startup failed', error);
}

Debug diagnostics

The FrontendMCP browser library is quiet by default. Enable WebSocket lifecycle and JSON-RPC frame diagnostics with the opt-in frontendMCP.trace setting shown above. Use trace: true to write structured events through console.debug, or pass a callback to route them to your own development logger.

Trace events include the actual parsed JSON-RPC messages. Authorization values and fields whose names indicate tokens, passwords, cookies, secrets, or API keys are replaced with [REDACTED] before the event reaches either logger.

Compliance trace

The repository includes a black-box test client built on the official MCP SDK. It records the exact JSON-RPC initialization, tool discovery, and tool-call messages in both directions. Authorization values and secret-shaped fields are redacted.

MCP_URL='https://relay.example/mcp/session-id' \
MCP_AUTHORIZATION='Bearer your-token' \
pnpm test:mcp-compliance -- --trace-file /tmp/frontendmcp-trace.jsonl

For FunctionBridge servers, the runner verifies server instructions, the search_functions and execute_javascript_code contracts, every discovery detail level, structured and empty search results, and a harmless execution containing return 42;. Pass --skip-call to limit the check to initialization and tools/list metadata.

Check out the examples directory for more complete implementations and use cases.

Architecture

Standard MCP clients typically communicate over Streaming HTTP or STDIO. FrontendMCP uses a relay server to bridge the gap between HTTP-based MCP clients and WebSocket-based communication with the frontend.

1. The relay server listens for incoming HTTP requests from an MCP client.
2. The frontend establishes a persistent WebSocket connection to the relay server using a unique UUID.
3. When the relay server receives an HTTP request for a specific UUID, it forwards the JSON-RPC message over the WebSocket.
4. The frontend MCP server processes the request and sends the response back through the WebSocket.
5. The relay server completes the HTTP request with the frontend's response.

The full protocol is detailed in PROTOCOL.md and the reference implementations are available in the server directory.

Use Cases

• Local state access without syncing data to a backend first
• UI interactions such as reading highlighted text, clicking buttons, or filling out forms
• Exposing frontend functions that call authenticated backend endpoints using the current user's browser session
• Reducing backend implementation work when generic computation or logic can be handled in the frontend
• Client-side code execution via FunctionBridge

Roadmap

• Additional examples and documentation
• WebRTC based MCPClient for peer-to-peer connections
• Community feedback and contributions to guide future development

Contributing

Issues and pull requests are welcome on GitHub.