# x402 Trinity MCP server

> Enables AI agents to autonomously pay for HTTP 402 resources using USDC with hard spending limits and local wallet management.

- Repository: https://github.com/devmster/x402-trinity
- Page: https://hostedmcp.org/servers/devmster/x402-trinity
- Transport: stdio
- Stars: 3
- Latest version: 0.2.4

## Install

### Claude Code

```sh
claude mcp add --env 'X402_PRIVATE_KEY=<YOUR_X402_PRIVATE_KEY>' --env 'X402_MAX_PER_REQUEST=<X402_MAX_PER_REQUEST>' --env 'X402_TOTAL_BUDGET=<X402_TOTAL_BUDGET>' x402-trinity -- npx -y x402-trinity
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "x402-trinity": {
      "command": "npx",
      "args": [
        "-y",
        "x402-trinity"
      ],
      "env": {
        "X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
        "X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
        "X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "x402-trinity": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "x402-trinity"
      ],
      "env": {
        "X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
        "X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
        "X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"x402-trinity","type":"stdio","command":"npx","args":["-y","x402-trinity"],"env":{"X402_PRIVATE_KEY":"<YOUR_X402_PRIVATE_KEY>","X402_MAX_PER_REQUEST":"<X402_MAX_PER_REQUEST>","X402_TOTAL_BUDGET":"<X402_TOTAL_BUDGET>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "x402-trinity": {
      "command": "npx",
      "args": [
        "-y",
        "x402-trinity"
      ],
      "env": {
        "X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
        "X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
        "X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add x402-trinity --env 'X402_PRIVATE_KEY=<YOUR_X402_PRIVATE_KEY>' --env 'X402_MAX_PER_REQUEST=<X402_MAX_PER_REQUEST>' --env 'X402_TOTAL_BUDGET=<X402_TOTAL_BUDGET>' -- npx -y x402-trinity
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.x402-trinity]
command = "npx"
args = ["-y", "x402-trinity"]

[mcp_servers.x402-trinity.env]
X402_PRIVATE_KEY = "<YOUR_X402_PRIVATE_KEY>"
X402_MAX_PER_REQUEST = "<X402_MAX_PER_REQUEST>"
X402_TOTAL_BUDGET = "<X402_TOTAL_BUDGET>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'X402_PRIVATE_KEY=<YOUR_X402_PRIVATE_KEY>' -e 'X402_MAX_PER_REQUEST=<X402_MAX_PER_REQUEST>' -e 'X402_TOTAL_BUDGET=<X402_TOTAL_BUDGET>' x402-trinity npx -- -y x402-trinity
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "x402-trinity": {
      "command": "npx",
      "args": [
        "-y",
        "x402-trinity"
      ],
      "env": {
        "X402_PRIVATE_KEY": "<YOUR_X402_PRIVATE_KEY>",
        "X402_MAX_PER_REQUEST": "<X402_MAX_PER_REQUEST>",
        "X402_TOTAL_BUDGET": "<X402_TOTAL_BUDGET>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `X402_PRIVATE_KEY` | yes | yes | Private key of the wallet that pays. Use a dedicated wallet holding only what you would accept losing. The server refuses to start without it. |
| `X402_MAX_PER_REQUEST` | yes | no | Hard ceiling for a single payment, in atomic units (USDC has 6 decimals, so 50000 is $0.05). Required: a model decides when payments happen, so the cap cannot come from the model. |
| `X402_TOTAL_BUDGET` | yes | no | Lifetime ceiling across all payments, in atomic units. Required for the same reason as the per-request cap. |
| `X402_ALLOW_HOSTS` | no | no | Comma-separated hosts that may be paid. Anything else is refused however convincing the challenge looks. |
| `X402_BUDGET_FILE` | no | no | Path to a file that makes the lifetime budget survive restarts. Without it the total resets every time the server starts. |
| `X402_NETWORKS` | no | no | Networks to accept. Defaults to base. |

## FAQ

### How does the agent pay for resources?

The server handles 402 Payment Required challenges by reading the challenge, checking it against user-defined limits, signing the transaction, and retrying the request.

### Does the agent need to pay gas fees?

No, the agent only needs USDC because the facilitator submits the transfer under EIP-3009.

### Can I limit how much the agent spends?

Yes, you must set mandatory spending caps including maximum amount per request and a total lifetime budget.