1.0.7 • Published 18h agoCLI

@msantagiulianab/x402-mcp-server

Licence

MIT

Version

1.0.7

Deps

Size

24 kB

Vulns

Weekly

Summary Dependency Versions

x402 MCP Server

A lightweight, zero-bloat Model Context Protocol (MCP) server that exposes the Solana Enterprise Payment Gateway's POST /api/v1/compliance/screen-address endpoint as an autonomous tool for AI agents (Claude Desktop, Cursor, VS Code Cline, ElizaOS).

The agent transparently negotiates and settles the x402 micro-payment on every screen: it receives the HTTP 402 Payment Required challenge, signs an Ed25519 channel voucher in-memory (Node.js built-in crypto, no Web3 SDK), and retries with a PAYMENT-SIGNATURE header.

Standalone npm package

The server is published to the npm registry as a standalone package — no clone or build step is required to run it:

npx -y @msantagiulianab/x402-mcp-server

See package.json for the current version and metadata. The package ships the compiled ESM dist/ bundle plus this README and the LICENSE.

Layout

agent-tools/mcp-server/
├── src/
│   ├── base58.ts          # zero-dependency Base58 codec
│   ├── ed25519.ts         # Node crypto Ed25519 keypair + canonical payload
│   ├── x402-client.ts     # autonomous X402Client (402 -> sign -> retry)
│   └── index.ts           # MCP server + tool registration
├── test/                  # offline unit + stdio integration tests
├── test-agent-call.js     # live verification against the running Docker stack
├── package.json
├── smithery.yaml          # Smithery registry manifest
└── tsconfig.json

Install & build

cd agent-tools/mcp-server
npm install
npm run build          # tsc -> dist/ (ESM)

Run (stdio transport)

npx -y @msantagiulianab/x402-mcp-server   # published package
# or, from a local checkout:
npm start
# or: node dist/index.js

Environment variables:

Variable	Default	Purpose
`X402_GATEWAY_URL`	`https://msb-solana-enterprise-payment-gateway.duckdns.org`	Gateway root URL
`X402_CHANNEL_ID`	`chan_smoke_test_001`	x402 payment channel id
`X402_PRIVATE_KEY_SEED`	sha256 of `smoke-test-payer-seed-v1`	64-hex or UTF-8 material seed

X402_GATEWAY_URL and X402_CHANNEL_ID are injected by the MCP host (Claude Desktop, Cline, Smithery, etc.); X402_PRIVATE_KEY_SEED is optional and defaults to the deterministic smoke-test payer.

The tool screen_solana_address:

Description: Inspect a Solana address against sanctions and threat intelligence databases. Automatically negotiates and settles micro-payments via x402.
Input: address — a valid Base58 Solana public key (decodes to 32 bytes).
Output: formatted JSON text containing verdict, riskScore, flags, and the evaluation timestamp.

Architecture & Sync Workflow

This component is one of three independently deployable surfaces in the repository. Changes flow differently depending on where they live:

Where the change lives	Sync / deploy action
Java backend (`src/main/...`)	Push to GitHub, then `git pull` on the Hetzner VPS to rebuild/restart the container or jar.
MCP server (`agent-tools/mcp-server/src/...`)	Bump `version` in `package.json`, then `npm publish`.
Documentation / `smithery.yaml` (`README.md`, `smithery.yaml`)	Push to GitHub only — no VPS reload and no `npm publish` required.

The backend and the MCP server deploy independently: a Java change does not require an npm publish, and an MCP change does not require a VPS reload. Documentation and registry metadata (smithery.yaml) ship purely via GitHub.

`smithery.yaml`

smithery.yaml is the Smithery registry manifest. It declares the stdio startCommand (npx -y @msantagiulianab/x402-mcp-server) and exposes two configurable fields — gatewayUrl and channelId — which map onto the X402_GATEWAY_URL and X402_CHANNEL_ID environment variables. Updating it only requires a GitHub push; the Smithery registry indexes it directly from the repository.

Tests

npm test

This compiles the project and runs:

base58.test.js — Base58 codec round-trips and 32-byte address validation.
ed25519.test.js — golden-vector check that the canonical payload and Ed25519 signature exactly match smoke-test.sh / the JVM PaymentVoucher layout.
x402-client.test.js — full 402→sign→retry negotiation against a mock gateway, with independent Ed25519 signature verification of the emitted voucher.
mcp-server.test.js — spawns the real server and drives it with an MCP client over stdio (list tools + call screen_solana_address).

Live verification against the running stack

With the Docker stack up (docker compose up -d --build):

npm run test:tool

This exercises the tool handler against http://localhost:8080:

Clean address 4Nd1mBQtrMJVYVfKf2PJy9NZGibCcTRxpETqdrBHu19Y → CLEAR_TO_TRANSACT.
Flagged address Fc1EwQUZyTEagaDvA1utHXCcZNyG1x2PLt2DfNu1cJdH → BLOCKED.

Client configuration

Claude Desktop

Add to claude_desktop_config.json:

macOS / Linux

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}

VS Code Cline

Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}