mcp-web

MCP-Web exposes your frontend as a set of MCP tools and visual components that AI agents can discover and invoke. By running the bridge, your frontend can publish tools and state, and AI agents can interact with them via MCP commands, charts, and automated UI actions. You can connect an AI agent either remotely, by pointing it at the bridge over the network, or locally via the built-in client that communicates through STDIO. The system supports dynamic tooling (tools generated from your schemas), state tooling with auto-generated getters/setters, and visual tools (MCP Apps) that render UI inside AI chat conversations. To get started, run the bridge with npx @mcp-web/bridge, which will start the WebSocket and MCP HTTP server on port 3001. Then expose tools in your frontend using @mcp-web/core so the AI agent can enumerate and call them. For remote connections, configure the agent to connect to the bridge’s URL (e.g., https://localhost:3001?token=your-auth-token). For local development, you can instead run a local client via @mcp-web/client and point it at your server via env variables such as MCP_SERVER_URL and AUTH_TOKEN.

Prerequisites:

• Node.js (LTS) and npm installed
• Basic familiarity with your frontend project setup

Install steps:

1. Install dependencies for your frontend project (if not already):

npm install

2. Install and run the MCP bridge (no global install required; use npx):

# Start the bridge (WebSocket + MCP HTTP) on port 3001
npx @mcp-web/bridge

3. (Optional) If you prefer to use the bridge via a local client, install the client package and run it as needed:

npm install @mcp-web/client
# Then configure your local client transport (STDIO) per your setup

4. In your frontend, install the core library and start exposing tools and state:

npm install @mcp-web/core

5. Connect your AI agent either remotely to the bridge URL or via the local client by configuring the appropriate mcpConfig as shown in the README.

Notes:

• The bridge runs on port 3001 by default; adjust PORT in the environment if needed.
• If using the local client transport, you’ll typically provide MCP_SERVER_URL (e.g., http://localhost:3002) and an AUTH_TOKEN.
• Ensure your frontend registers tools and state through @mcp-web/core so they appear to AI agents as MCP tools and apps.

Tips and common considerations:

• Default bridge port is 3001; the local client uses port 3002 for MCP HTTP access when configured that way.
• For remote MCP connections, you’ll typically supply an authentication token in the bridge URL or via environment variables for the client.
• Use the dynamic tooling features to auto-generate tools from your Zod schemas and expose state with auto-generated getters/setters.
• MCP Apps allow rendering UI components inline in AI chat, enabling visual interactions with frontend components from AI conversations.
• If you encounter connectivity issues, verify that the bridge is reachable at the configured URL and that any firewalls or VPNs allow WebSocket and HTTP traffic on port 3001.
• When developing locally, the client is the recommended option for a smooth workflow, and it doubles as the fastest path to iteration.