npm package: @henrylabs/x402-mcp
Description: A Model Context Protocol (MCP) server for Henry Labs' x402 commerce APIs
Author: Henry Labs
Latest version: 1.0.2

# Henry Labs x402 MCP Server

A Model Context Protocol (MCP) server that provides AI agents with access to Henry Labs' x402 commerce APIs, including product search, cart management, checkout, and payment processing.

## Features

- **Product Discovery**: Search products, get details, enrich product data, image search
- **Cart Management**: Add items, view cart, delete items
- **Checkout**: Single checkout, network token checkout, session-based checkout
- **Order Management**: Check order status, list orders, delete orders
- **Wallet**: Card collection, stored card management
- **Merchant**: Merchant listings, status, shipping information
- **x402 Payment Integration**: Built-in support for x402 payment protocol

## Installation

Install the package globally via npm:

```bash
npm install -g @henrylabs/x402-mcp
```

Or with your preferred package manager:

```bash
# Using pnpm
pnpm install -g @henrylabs/x402-mcp

# Using yarn
yarn global add @henrylabs/x402-mcp
```

## Configuration

This MCP server requires environment variables to be configured through your MCP client's settings.

### Required Environment Variables

| Variable             | Description                       | Example                                                          |
| -------------------- | --------------------------------- | ---------------------------------------------------------------- |
| `WALLET_PRIVATE_KEY` | EVM private key for x402 payments | `0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab` |

### Optional Environment Variables

| Variable          | Description            | Default   | Options                   |
| ----------------- | ---------------------- | --------- | ------------------------- |
| `RESOURCE_SERVER` | API environment to use | `sandbox` | `sandbox` or `production` |

### Environment Variable Validation

The server validates all environment variables on startup. If validation fails, you'll see a clear error message:

## MCP Client Setup

### Cursor

1. Install the package globally: `npm install -g @henrylabs/x402-mcp`
2. Open Cursor Settings → MCP
3. Add the server configuration to your `mcp.json` file:

**Linux**: `~/.config/Cursor/User/globalStorage/mcp.json`
**macOS**: `~/Library/Application Support/Cursor/User/globalStorage/mcp.json`
**Windows**: `%APPDATA%\Cursor\User\globalStorage\mcp.json`

```json
{
  "mcpServers": {
    "henry-x402": {
      "command": "henry-mcp",
      "env": {
        "WALLET_PRIVATE_KEY": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
        "RESOURCE_SERVER": "sandbox"
      }
    }
  }
}
```

**Note:** Set `RESOURCE_SERVER` to `"production"` when ready to use the live API.

4. Restart Cursor

### Claude Code

1. Install the package globally: `npm install -g @henrylabs/x402-mcp`
2. Add to your Claude Code settings (`.clauderc` or settings file):

```json
{
  "mcpServers": {
    "henry-x402": {
      "command": "henry-mcp",
      "env": {
        "WALLET_PRIVATE_KEY": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
        "RESOURCE_SERVER": "sandbox"
      }
    }
  }
}
```

**Note:** Set `RESOURCE_SERVER` to `"production"` when ready to use the live API.

3. Restart Claude Code

### Other MCP Clients

1. Install the package globally: `npm install -g @henrylabs/x402-mcp`
2. Configure your MCP client with:

- **Command**: `henry-mcp`
- **Environment Variables**:
  - `WALLET_PRIVATE_KEY` (required): Your EVM private key (66 characters starting with 0x)
  - `RESOURCE_SERVER` (optional): Either `sandbox` (default) or `production`

Refer to your client's documentation for specific configuration steps.

## Available Tools

| Tool                            | Description                | Method |
| ------------------------------- | -------------------------- | ------ |
| `search-product`                | Search products by query   | POST   |
| `product-detail`                | Get product details        | GET    |
| `enrich-product`                | Enrich product data        | POST   |
| `enrich-by-id`                  | Enrich product by ID       | GET    |
| `variant-check`                 | Check product variants     | POST   |
| `variant-check-by-id`           | Check variants by ID       | GET    |
| `image-search`                  | Search by image            | POST   |
| `add-to-cart`                   | Add item to cart           | POST   |
| `cart-checkout`                 | Checkout cart              | POST   |
| `delete-cart-items`             | Delete all cart items      | DELETE |
| `delete-cart-item`              | Delete single cart item    | DELETE |
| `session-quote`                 | Get checkout session quote | POST   |
| `session-confirm`               | Confirm checkout session   | POST   |
| `single-checkout`               | Single item checkout       | POST   |
| `single-network-token-checkout` | Network token checkout     | POST   |
| `order-status`                  | Check order status         | GET    |
| `order-delete`                  | Delete order               | DELETE |
| `initiate-card-collect`         | Initiate card collection   | POST   |
| `collect-cards`                 | Collect cards              | POST   |
| `card-delete`                   | Delete stored card         | DELETE |
| `merchants-list`                | List merchants             | GET    |
| `merchant-status`               | Check merchant status      | GET    |
| `merchant-shipping-info`        | Get merchant shipping info | GET    |
| `get-order-list`                | Get order list             | GET    |
| `get-cart-items`                | Get cart items             | GET    |
| `get-stored-cards`              | Get stored cards           | GET    |

## Local Development

For contributors or local development:

```bash
# Clone the repository
git clone https://github.com/henrylabs/x402-mcp.git
cd x402-mcp

# Install dependencies
npm install

# Run in development mode
bun run dev

# Or run directly
bun run start

# Build the package
npm run build
```

## Dependencies

- `@modelcontextprotocol/sdk` - MCP server SDK
- `@x402/axios` - x402 payment integration for Axios
- `@x402/evm` - EVM scheme for x402
- `viem` - Ethereum utilities
- `zod` - Schema validation

## License

MIT