mcp-x402

# MCP x402 — Evidence-Backed Web Verification for AI Agents

## Verify a seller, product, offer, policy, or claim before an agent acts

Give an AI agent a public HTTP(S) page and 1 to 10 concrete conditions. The `verificar_condicoes` tool returns an evidence-based decision for every condition:

- `confirmado` — the page clearly supports the condition.
- `rejeitado` — the page clearly contradicts the condition.
- `incerto` — the available page evidence is insufficient.

Each verification includes the final source URL, page title, timestamp, condition-by-condition explanation, quoted evidence when available, a unique `verificationId`, and a SHA-256 `pageHash`.

### Designed for

- AI purchasing and procurement agents;
- seller, product and offer verification;
- pre-purchase due diligence;
- policy and terms checking;
- commercial automation that requires evidence before taking action.

### Simple x402 integration

- Free preflight validation before payment.
- `$0.05 USDC` per verification on Base mainnet.
- No account or subscription required.
- Available through MCP and HTTP.
- Ready-to-run buyer included in this repository.
- Coinbase x402 validation passed and Bazaar discovery enabled.

### Live endpoints

- MCP: `https://mcp-x402-production.up.railway.app/mcp`
- Free verification preflight: `POST https://mcp-x402-production.up.railway.app/preflight/verify-conditions`
- Paid verification: `POST https://mcp-x402-production.up.railway.app/verify-conditions`
- Health: `GET https://mcp-x402-production.up.railway.app/health`

The service also provides paid public URL analysis and general AI consultation through `analisar_url` and `consultar_ia`.

## Live Service

- Base URL: `https://mcp-x402-production.up.railway.app`
- Health check: `GET /health`
- MCP endpoint: `POST /mcp`
- Paid URL analysis: `POST /analyze`
- Price: `$0.05 USDC` per paid request
- Network: Base mainnet (`eip155:8453`)

## Production Status

- Production deployment active on Railway
- x402 version 2 payment flow
- Base mainnet payments (`eip155:8453`)
- Coinbase x402 validation passed
- Simulation accepted with HTTP 402
- Bazaar discovery metadata enabled
- Coinbase index active

## MCP Tools

## Decision verification

### `verificar_condicoes` — $0.05 USDC

A paid decision-verification tool for agents.

Give it a public URL and one or more concrete conditions. It returns a decision based only on evidence extracted from that page:

- `confirmado` — the page clearly proves the condition.
- `rejeitado` — the page clearly contradicts the condition.
- `incerto` — the page does not provide enough evidence.

Each result includes the final source URL, page title, verification timestamp, condition-by-condition explanation, and a short quoted proof where available.

Example conditions:

- “The page identifies the seller.”
- “The product is available in Portugal.”
- “The page shows a price in euros.”
- “The document states that the service supports x402.”

This is designed for agents that need an evidence-based decision before taking the next action.

| Tool | Description | Price |
| --- | --- | --- |
| `consultar_ia` | Sends a prompt to the OpenAI Responses API. | $0.02 USDC |
| `analisar_url` | Fetches and analyzes a public HTTP or HTTPS page. | $0.05 USDC |
| `verificar_condicoes` | Verifies concrete conditions on a public page and returns evidence-based decisions. | $0.05 USDC |

## Technology

- Node.js and TypeScript
- Express
- Model Context Protocol
- OpenAI Responses API
- x402 payments
- viem
- Cheerio
- Railway

## Security

- HTTPS provided by Railway
- Helmet security headers
- Rate limit of 100 requests per 15 minutes
- Structured request logs with unique request IDs
- Host validation and Railway health-check support
- Restricted OpenAI API key with access only to `/v1/responses`
- Environment files and secrets excluded from Git

## Environment Variables

### Server

| Variable | Required | Description |
| --- | --- | --- |
| `OPENAI_API_KEY` | Yes | OpenAI project API key. |
| `OPENAI_MODEL` | No | OpenAI model. Defaults to `gpt-5-mini`. |
| `HOST` | No | Listening host. Defaults to `0.0.0.0`. |
| `PORT` | No | Listening port. Defaults to `3000`. |
| `RAILWAY_PUBLIC_DOMAIN` | Railway | Automatically supplied by Railway. |

### Local Buyer

| Variable | Required | Description |
| --- | --- | --- |
| `EVM_PRIVATE_KEY` | Yes | Private key of the Base mainnet buyer wallet. Never commit this value. |

Example local `.env.test` file:

```env
EVM_PRIVATE_KEY=your_private_key_here
```

## Local Development

Install dependencies:

```bash
npm install
```

Start the development server:

```bash
npm run dev
```

Build the project:

```bash
npm run build
```

Start the compiled server:

```bash
npm start
```

## Health Check

The health endpoint is public and does not require payment:

```bash
curl https://mcp-x402-production.up.railway.app/health
```


## Ready-to-Run x402 Buyer

The repository includes ready-to-run buyers for applications and AI agents. The MCP buyer connects to the live service, validates the x402 payment requirements against Base mainnet USDC and a maximum payment of $0.05, signs the payment, retries the same tool call, and prints the settlement receipt and result.

Clone and prepare the buyer:

```bash
git clone https://github.com/Diogoup26/mcp-x402.git
cd mcp-x402
npm install
```

Create a local `.env.test` file in the project root:

```env
EVM_PRIVATE_KEY=0xYOUR_64_HEX_CHARACTER_PRIVATE_KEY
```

Never commit `.env.test` or expose the private key.

Build the project:

```bash
npm run build
```

The following commands authorize real x402 payments on Base mainnet:

- `consultar_ia`: $0.02 USDC
- `analisar_url`: $0.05 USDC
- `verificar_condicoes`: $0.05 USDC

### HTTP URL Analysis

```bash
npm run analyze -- "https://example.com" "Summarize this page."
```

### HTTP Decision Verification

```bash
npm run verify -- "https://example.com" "The page identifies the seller."
```

### MCP URL Analysis

```bash
npm run mcp:analyze -- "https://example.com" "Summarize this page."
```

### MCP AI Consultation

```bash
npm run mcp:consult -- "Reply only with: MCP OK"
```

### MCP Decision Verification

```bash
npm run mcp:verify -- "https://example.com" "The page identifies the seller."
```

A successful MCP payment prints:

- `PAGAMENTO MCP: success`
- the settlement receipt
- the tool response

The MCP buyer never prints the private key and rejects any payment that:

- is not on Base mainnet;
- does not use the configured Base USDC contract;
- exceeds $0.05 USDC.
## Deployment

The `main` branch is connected to Railway. Every successful push triggers a new deployment. Railway uses:

```bash
npm run build
npm start
```

The deployment health-check path is `/health`.

## License

ISC