npm package: @mcp-web/client
Description: 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.
Latest version: 0.1.3

# 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:

```bash
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:

```typescript
// 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:

```json
{
  "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:

```json
{
  "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

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

```
Claude Desktop ↔ MCP Client ↔ Bridge Server ↔ Web Application
```

## Setup Process

1. **Install the web library** in your web application:
   ```bash
   npm install @mcp-web/core
   ```

2. **Integrate MCP tools** in your web application using `@mcp-web/core`

3. **Get the configuration** from your web app (usually shown in a help dialog)

4. **Copy the configuration** to Claude Desktop's config file

5. **Restart Claude Desktop** to load the new MCP server

6. **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:

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

## Examples

See the [HiGlass demo](../../demos/higlass) 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