@mcp-web/client

MCP Client

An MCP (Model Context Protocol) client that connects AI applications like Claude Desktop to the MCP bridge server, enabling AI-powered control of web applications.

Overview

This package provides the MCP client that acts as a bridge between AI applications (like Claude Desktop) and web applications. It should be installed and configured in your AI application to connect to the MCP bridge server that communicates with your web application.

Installation

The MCP client is typically installed via npm when configuring your AI application:

npx @mcp-web/client

Configuration

For Claude Desktop

The MCP client is configured through Claude Desktop's configuration file. However, you should not manually configure this. Instead, the configuration is automatically generated by your web application using the @mcp-web/core library.

Getting Configuration from Your Web App

When you integrate @mcp-web/core into your web application, it automatically generates the correct MCP configuration. Your web application should expose this configuration to users (typically through a help dialog or setup page).

Here's how a web application typically exposes the configuration:

// In your web application
import { MCPWeb } from '@mcp-web/core';

const mcp = new MCPWeb({
  name: 'My Web App',
  description: 'Control my web application',
});

// Get the MCP configuration for Claude Desktop
const mcpConfig = mcp.mcpConfig;

// Display this to users so they can copy it to Claude Desktop
console.log(JSON.stringify(mcpConfig, null, 2));

Example Configuration

The generated configuration will look like this:

{
  "My Web App": {
    "command": "npx",
    "args": ["@mcp-web/client"],
    "env": {
      "MCP_SERVER_URL": "http://localhost:3002",
      "AUTH_TOKEN": "your-unique-auth-token"
    }
  }
}

This configuration should be added to your Claude Desktop config file at:

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

Under the mcpServers section:

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

Environment Variables

The MCP client uses these environment variables (automatically set by the configuration):

• MCP_SERVER_URL: URL of the bridge server (typically http://localhost:3002)
• AUTH_TOKEN: Authentication token for secure communication (automatically generated by your web app)

How It Works

• Web Application: Uses @mcp-web/core to register tools and connect to the bridge server
• Bridge Server: Mediates communication between the web app and MCP clients
• MCP Client (this package): Connects Claude Desktop to the bridge server
• Claude Desktop: Uses the MCP client to access tools from your web application

Claude Desktop ↔ MCP Client ↔ Bridge Server ↔ Web Application

Setup Process

• Install the web library in your web application:

  npm install @mcp-web/core
  

• Integrate MCP tools in your web application using @mcp-web/core

• Get the configuration from your web app (usually shown in a help dialog)

• Copy the configuration to Claude Desktop's config file

• Restart Claude Desktop to load the new MCP server

• Start using your web application through Claude Desktop!

Troubleshooting

• Connection refused: Make sure your web application is running and the bridge server is active
• Authentication failed: The auth token in Claude Desktop config must match the one generated by your web app
• Tools not available: Ensure your web application has registered tools using mcp.addTool()

Security

The MCP client uses secure authentication tokens that are:

• Automatically generated by your web application
• Unique per application instance
• Required for all bridge server communications

Development

This package is part of the MCP Frontend Integration System. For development:

npm run build    # Build the client
npm run dev      # Watch mode for development

Examples

See the HiGlass demo for a complete example of:

• Setting up @mcp-web/core in a React application
• Registering various types of tools
• Displaying the MCP configuration to users
• Complete integration workflow