MCP Agentic Wallet — open-source session management for x402 MCP server

MCP Agentic Wallet

Open-source EIP-2612 Permit-based wallet sessions for AI agents.

The reference implementation for paid MCP servers — verify signatures, manage sessions, settle on-chain. No API keys. No recurring charges.

What This Is

A human connects their crypto wallet, signs a one-time EIP-2612 Permit (gasless — no transaction fee), and receives a session token. AI agents use this token in MCP requests to pay for tool calls with USDC on Base. The server settles each call on-chain via transferFrom.

No API keys. No recurring charges. No per-call wallet signatures. The permit is the policy.

This is the reference implementation used by mcpvot.xyz — an x402 payment facilitator for MCP servers. The open-source core (@mcp-agentic-wallet/core) is framework-agnostic and works with any MCP server or Next.js app.

Quick Start

1. Install the core library

npm install @mcp-agentic-wallet/core viem

2. Use in your MCP server

import { InMemoryStore, settleCall } from '@mcp-agentic-wallet/core';

const store = new InMemoryStore();

// In your MCP tool handler:
const token = req.headers.get('Session-Token');
const session = store.getSession(token);
if (!session) return new Response('Payment required', { status: 402 });

// Consume budget ($0.005 = 5000 atomic USDC units)
const result = store.consumeBudget(token, 5000n);
if (!result.ok) return new Response('Insufficient budget', { status: 402 });

// Settle on-chain
await settleCall(session.humanAddress, 5000n, {
  treasuryAddress: process.env.TREASURY_ADDRESS!,
  hotWalletKey: process.env.HOT_WALLET_PRIVATE_KEY,
});

return Response.json({ result: 'your data' });

3. Run the reference server

git clone https://github.com/MCPVOT/mcp-agentic-wallet.git
cd mcp-agentic-wallet
npm install
cp .env.example .env.local  # Configure your treasury + hot wallet key
npm run dev

Visit http://localhost:3000/wallet to connect a wallet and authorize a session.

How It Works

Human                          Server                        Agent
  │                              │                              │
  │── connect wallet ──────────►│                              │
  │── sign EIP-2612 Permit ───►│                              │
  │   (gasless, 1-time)           │── verify signature ──────►│ (on-chain)
  │                              │── submit permit() ────────►│ (on-chain, gas)
  │                              │── create session ──────────┐│
  │◄─ return session token ─────│◄───────────────────────────┘│
  │                              │                              │
  │                              │◄── Session-Token header ────│
  │                              │── consume budget ───────────┐│
  │                              │── transferFrom() ──────────►││ (on-chain, gas)
  │                              │── return tool data ─────────┘│
  │                              │◄──────────────────────────────│

Core Library (@mcp-agentic-wallet/core)

Shortened. The full README is on GitHub.