# x402-mcp

A TypeScript MCP (Model Context Protocol) Server with Express.js integration for the x402 Payment Protocol.

## Overview

This is a **hybrid MCP server** that combines:

- **MCP Server**: Provides tools to interact with the x402 payment protocol through the Model Context Protocol
- **Express HTTP Server**: Creates payment-protected HTTP endpoints using x402 payment middleware

This allows AI assistants and MCP clients to both manage x402 payments AND dynamically create HTTP endpoints protected by cryptocurrency payments. Built with TypeScript, the official MCP SDK, and x402-express middleware.

## Features

### 🔧 MCP Tools for Payment Management

- **x402_create_payment_request**: Create a new payment request with specified price and details
- **x402_check_payment_status**: Check the status of an existing payment request
- **x402_get_config**: Get the current x402 configuration (payment address, network, facilitator URL)
- **x402_list_networks**: List available networks for x402 payments

### 🌐 MCP Tools for Express Endpoint Management

- **x402_create_protected_endpoint**: Dynamically create HTTP endpoints protected by x402 payment middleware
- **x402_list_protected_endpoints**: List all protected endpoints on the Express server
- **x402_get_express_server_status**: Get Express server status (running state, port, endpoint count)
- **x402_update_endpoint_price**: Update the price for an existing protected endpoint

### ⚙️ Configuration

- **Payment Address**: `0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7`
- **Network**: Base Sepolia (testnet) - change to "base" for mainnet
- **Payment Token**: USDC (stablecoin)
- **Facilitator URL**: `https://x402.org/facilitator` (testnet)
- **Express Port**: `4021`

## Installation

```bash
npm install
```

## Development

Run the server in development mode with hot reload:

```bash
npm run dev
```

## Build

Compile TypeScript to JavaScript:

```bash
npm run build
```

## Production

Run the compiled server:

```bash
npm start
```

## Architecture

This is a **hybrid server** that runs two servers simultaneously:

```
┌─────────────────────────────────────────────────────────────┐
│                      x402-mcp Process                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────────────────┐  ┌──────────────────────────┐│
│  │   MCP Server (stdio)     │  │  Express HTTP Server     ││
│  │                          │  │  (Port 4021)             ││
│  │  • Tool Management       │  │                          ││
│  │  • Payment Requests      │  │  • Payment Middleware    ││
│  │  • Endpoint Management   │  │  • Protected Routes      ││
│  │  • Configuration         │  │  • Health Check          ││
│  └──────────────────────────┘  └──────────────────────────┘│
│                                                              │
│              Both use X402_CONFIG shared state               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    x402 Facilitator
                 (Payment Verification)
```

### Key Components

1. **MCP Server**: Communicates via stdio, provides tools to AI assistants
2. **Express Server**: HTTP server with x402 payment middleware
3. **ExpressServerManager**: Manages Express lifecycle and protected endpoints
4. **X402Handler**: Handles manual payment request creation and tracking
5. **x402-express Middleware**: Intercepts HTTP requests, enforces payments

## Project Structure

```
x402-mcp/
├── src/
│   └── index.ts          # Main implementation (MCP + Express hybrid)
├── dist/                 # Compiled JavaScript output
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── .gitignore           # Git ignore rules
└── README.md            # This file
```

## Usage with MCP Clients

### Configuration

Add this server to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "x402-mcp": {
      "command": "node",
      "args": ["/path/to/x402-mcp/dist/index.js"]
    }
  }
}
```

For development:

```json
{
  "mcpServers": {
    "x402-mcp": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/x402-mcp"
    }
  }
}
```

### Example Tool Calls

#### Create a Protected HTTP Endpoint

```json
{
  "name": "x402_create_protected_endpoint",
  "arguments": {
    "path": "/weather",
    "method": "GET",
    "price": "$0.001",
    "description": "Get current weather data for any location",
    "responseData": {
      "weather": "sunny",
      "temperature": 72,
      "humidity": 45
    },
    "inputSchema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "City name"
        }
      }
    },
    "outputSchema": {
      "type": "object",
      "properties": {
        "weather": { "type": "string" },
        "temperature": { "type": "number" },
        "humidity": { "type": "number" }
      }
    }
  }
}
```

**Response:**

```json
{
  "success": true,
  "message": "Protected endpoint created successfully",
  "data": {
    "endpoint": "GET /weather",
    "url": "http://localhost:4021/weather",
    "price": "$0.001",
    "description": "Get current weather data for any location",
    "network": "base-sepolia",
    "payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7"
  }
}
```

Now when someone accesses `http://localhost:4021/weather` without payment, they'll receive a 402 Payment Required response with payment instructions!

#### Create Payment Request

```json
{
  "name": "x402_create_payment_request",
  "arguments": {
    "price": "$0.50",
    "description": "Access to premium API endpoint",
    "resource": "/api/premium/data",
    "maxTimeoutSeconds": 120
  }
}
```

**Response:**

```json
{
  "success": true,
  "message": "Payment request created successfully",
  "data": {
    "paymentId": "x402_1234567890_abc123",
    "paymentUrl": "https://x402.org/facilitator/pay?id=...",
    "price": "$0.50",
    "network": "base-sepolia",
    "payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7",
    "description": "Access to premium API endpoint",
    "expiresAt": "2024-01-01T12:02:00.000Z"
  }
}
```

#### List All Protected Endpoints

```json
{
  "name": "x402_list_protected_endpoints",
  "arguments": {}
}
```

**Response:**

```json
{
  "success": true,
  "message": "Found 1 protected endpoint(s)",
  "data": [
    {
      "method": "GET",
      "path": "/weather",
      "price": "$0.001",
      "description": "Get current weather data for any location",
      "url": "http://localhost:4021/weather"
    }
  ]
}
```

#### Get Express Server Status

```json
{
  "name": "x402_get_express_server_status",
  "arguments": {}
}
```

**Response:**

```json
{
  "success": true,
  "message": "Express server is running",
  "data": {
    "isRunning": true,
    "port": 4021,
    "network": "base-sepolia",
    "payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7",
    "facilitatorUrl": "https://x402.org/facilitator",
    "endpointCount": 1,
    "endpoints": [...]
  }
}
```

#### Check Payment Status

```json
{
  "name": "x402_check_payment_status",
  "arguments": {
    "paymentId": "x402_1234567890_abc123"
  }
}
```

**Response:**

```json
{
  "success": true,
  "data": {
    "paymentId": "x402_1234567890_abc123",
    "status": "pending",
    "paid": false,
    "price": "$0.50",
    "network": "base-sepolia",
    "createdAt": "2024-01-01T12:00:00.000Z",
    "expiresAt": "2024-01-01T12:02:00.000Z"
  }
}
```

#### Get Configuration

```json
{
  "name": "x402_get_config",
  "arguments": {}
}
```

**Response:**

```json
{
  "success": true,
  "message": "Current x402 configuration",
  "data": {
    "payTo": "0x243E0B615BfEa0f315109b8b415e3D6b9c3131F7",
    "network": "base-sepolia",
    "facilitatorUrl": "https://x402.org/facilitator"
  }
}
```

#### List Networks

```json
{
  "name": "x402_list_networks",
  "arguments": {}
}
```

**Response:**

```json
{
  "success": true,
  "message": "Available networks for x402 payments",
  "data": [
    {
      "name": "base",
      "displayName": "Base Mainnet",
      "chainId": 8453,
      "currency": "ETH",
      "stablecoin": "USDC",
      "isMainnet": true
    },
    {
      "name": "base-sepolia",
      "displayName": "Base Sepolia Testnet",
      "chainId": 84532,
      "currency": "ETH",
      "stablecoin": "USDC",
      "isMainnet": false
    },
    {
      "name": "avalanche",
      "displayName": "Avalanche C-Chain",
      "chainId": 43114,
      "currency": "AVAX",
      "stablecoin": "USDC",
      "isMainnet": true
    },
    {
      "name": "solana",
      "displayName": "Solana Mainnet",
      "chainId": null,
      "currency": "SOL",
      "stablecoin": "USDC",
      "isMainnet": true
    }
  ]
}
```

## Error Handling

The server includes comprehensive error handling:

- **Payment not found**: Returns error when checking status of non-existent payment
- **Invalid payment status**: Prevents operations on payments in wrong state
- **Expired payments**: Automatically marks pending payments as expired
- **Invalid arguments**: Validates using Zod schemas with detailed error messages

## Technology Stack

- **TypeScript**: Type-safe development
- **Node.js**: Runtime environment
- **MCP SDK**: Official Model Context Protocol SDK
- **x402-express**: x402 Payment Protocol integration
- **Zod**: Runtime type validation

## How x402 Protocol Works

The x402 protocol is a standard for HTTP-based cryptocurrency payments. This hybrid MCP server provides two complementary approaches:

### Approach 1: Express Middleware (Recommended)

This is the standard x402 flow using Express middleware:

1. **Create Protected Endpoint**: Use `x402_create_protected_endpoint` to dynamically create an HTTP endpoint
2. **Client Makes Request**: When a client accesses the endpoint without payment, they receive **HTTP 402 Payment Required**
3. **Payment Instructions**: The 402 response includes payment details (amount, address, network) in the response body
4. **Client Pays**: Client submits payment transaction on the blockchain
5. **Retry with Proof**: Client retries the request with `X-PAYMENT` header containing cryptographic proof of payment
6. **Middleware Verifies**: x402 middleware verifies the payment via the facilitator
7. **Access Granted**: If valid, the endpoint returns the protected content

### Approach 2: Manual Payment Requests

For custom payment flows:

1. Call `x402_create_payment_request` with price and details
2. Server returns a payment URL and unique payment ID
3. User completes payment through the payment URL
4. Call `x402_check_payment_status` to verify payment completion
5. Grant access to resource once payment is confirmed

### Network Support

- **Base** (mainnet) and **Base Sepolia** (testnet)
- **Avalanche C-Chain** (mainnet) and **Avalanche Fuji** (testnet)
- **Solana** (mainnet) and **Solana Devnet** (testnet)
- All payments processed in **USDC stablecoin**

## Use Cases

- **AI API Monetization**: Charge for expensive AI model inference calls
- **Content Paywalls**: Gate premium content behind cryptocurrency payments
- **Micro-transactions**: Enable small payments for individual API calls (as low as $0.001)
- **Resource Access Control**: Manage access to computational resources
- **Dynamic API Marketplaces**: AI agents can discover and pay for APIs automatically
- **Pay-per-use Services**: Weather data, stock prices, translation APIs, etc.

## Running on Mainnet

To accept real payments on mainnet, you need to make a few changes:

### 1. Set up CDP API Keys

1. Sign up at [cdp.coinbase.com](https://cdp.coinbase.com)
2. Create a new project and generate API credentials
3. Set environment variables:
   ```bash
   export CDP_API_KEY_ID=your-api-key-id
   export CDP_API_KEY_SECRET=your-api-key-secret
   ```

### 2. Update Configuration in `src/index.ts`

```typescript
// Uncomment the facilitator import
import { facilitator } from "@coinbase/x402";

const X402_CONFIG = {
  payTo: "0xYourMainnetAddress", // Your real mainnet wallet address
  network: "base" as const, // Change from "base-sepolia" to "base"
  facilitatorUrl: "https://x402.org/facilitator", // Not used for mainnet
  expressPort: 4021,
};
```

### 3. Update Express Middleware to Use CDP Facilitator

In the `applyPaymentMiddleware()` method:

```typescript
private applyPaymentMiddleware() {
  if (Object.keys(this.routeConfigs).length > 0) {
    this.app.use(paymentMiddleware(
      X402_CONFIG.payTo,
      this.routeConfigs,
      facilitator // Use CDP facilitator instead of testnet URL
    ));
  }
}
```

## Customization

### Testnet Configuration (Current)

```typescript
const X402_CONFIG = {
  payTo: "0xYourAddress", // Your receiving wallet address
  network: "base-sepolia" as const, // or "avalanche-fuji", "solana-devnet"
  facilitatorUrl: "https://x402.org/facilitator",
  expressPort: 4021,
};
```

### Mainnet Configuration

```typescript
const X402_CONFIG = {
  payTo: "0xYourAddress", // Your receiving wallet address
  network: "base" as const, // or "avalanche", "solana"
  facilitatorUrl: "https://x402.org/facilitator",
  expressPort: 4021,
};
```

**Note**: When you specify prices like `"$0.50"`, the x402 protocol automatically processes payments in USDC on the selected network.

## Resources

- [x402 Protocol Documentation](https://x402.org)
- [x402-express Package](https://www.npmjs.com/package/x402-express)
- [Avalanche Network](https://www.avax.network)
- [MCP SDK Documentation](https://modelcontextprotocol.io)

## License

MIT