Skip to main content
@veil-cash/mcp is a local MCP server that wraps @veil-cash/sdk and exposes Veil as Base MCP-compatible tools for agents. It runs alongside Base MCP: Veil prepares private and calldata actions, and Base MCP submits public transactions via send_calls.

​
Install

Add Veil MCP to your client’s mcpServers, beside Base MCP: 
{
  "mcpServers": {
    "base-mcp": { "url": "https://mcp.base.org" },
    "veil": {
      "command": "npx",
      "args": ["-y", "@veil-cash/mcp"]
    }
  }
}
Use the npm package, not a GitHub install—it’s versioned and resolves its @veil-cash/sdk dependency automatically. Pin a version with @veil-cash/mcp@0.2.1 for reproducibility. For clients that start tools at session startup, install globally (npm install -g @veil-cash/mcp) and use "command": "veil-mcp" to avoid per-launch npm resolution.

​
Hermes Agent

Hermes Agent users can add Veil MCP as a stdio server in config.yaml: 
mcp_servers:
  veil:
    command: veil-mcp
    connect_timeout: 10

​
Enabling fund-moving tools

The server starts read-only with no configuration (veil_status, veil_x402_quote, veil_get_balances). To enable veil_pay_x402, veil_withdraw, and veil_transfer, provide VEIL_KEY (and optionally a dedicated RPC_URL): 
{
  "mcpServers": {
    "veil": {
      "command": "npx",
      "args": ["-y", "@veil-cash/mcp"],
      "env": {
        "VEIL_KEY": "0x...",
        "RPC_URL": "https://your-base-rpc"
      }
    }
  }
}
Configure RPC_URL with a dedicated Base RPC endpoint. Private balance and proof-building flows pull Merkle data, historical events, and queue state, which can exceed public RPC rate limits. Use veil_init_keypair to generate a random local keypair—it writes .env.veil and returns only the public deposit key.

​
Tools

ToolPurpose
veil_init_keypairGenerate and save a random local Veil keypair
veil_statusCheck key, relay, wallet, and registration status
veil_get_balancesRead wallet, queue, and private balances
veil_deposit_statusCheck one queued deposit by pool and nonce
veil_wait_for_depositPoll a queued deposit until accepted/rejected/refunded
veil_prepare_registerReturn Base send_calls calldata for registration
veil_prepare_depositReturn Base send_calls calldata for ETH/USDC deposits
veil_withdrawSubmit a private withdrawal through the Veil relay
veil_transferSubmit a private transfer through the Veil relay
veil_consolidate_utxosMerge fragmented private UTXOs into fewer notes
veil_pay_x402Pay an x402 resource from private USDC via any facilitator
veil_x402_quoteProbe an x402 resource for price/requirement without paying
veil_x402_receiptsList local x402 spend history and total USDC spent
veil_x402_payer_balancesInspect USDC left on deterministic x402 payer EOAs
veil_subaccount_statusRead subaccount status

​
Public vs private flows

veil_prepare_register and veil_prepare_deposit return { chain, calls } to pass directly to Base MCP send_calls—these are ordinary onchain transactions from your wallet: 
{
  "chain": "base",
  "calls": [{ "to": "0x...", "value": "0x0", "data": "0x..." }]
}
Deposits treat amount as the net amount intended to land in Veil; the 0.3% protocol fee is included in the prepared calldata. After Base MCP confirms, the deposit enters the Veil queue. For addresses without instant verification, 0xbow screening applies first (typically ~15 minutes, up to 5 days for complex cases); once approved, queue processing into private balance is typically ~8–12 minutes. Track deposits with veil_deposit_status or veil_get_balances. See Verified Users for instant paths. If veil_prepare_register returns action: "alreadyRegistered" with an empty calls array, skip send_calls and proceed to deposit or balance checks. Private actions (veil_withdraw, veil_transfer, veil_pay_x402) build proofs locally and submit through the Veil relay instead of Base MCP.

​
x402 payments

veil_pay_x402 pays a standard x402 v2 Base USDC exact resource from your private USDC balance, with a spend cap, pre-flight probe, and funded-payer reuse. The full flow and scope are on the Private x402 Payments page. Heavy x402 usage can fragment private UTXOs; when veil_get_balances reports needsConsolidation, call veil_consolidate_utxos to merge notes.

​
Safety

MCP responses never include VEIL_KEY, wallet private keys, proof arguments, nullifiers, encrypted outputs, x402 signatures, or private relay internals. veil_withdraw, veil_transfer, and veil_pay_x402 require confirm: true because they submit through the Veil relay rather than Base MCP approval links. Verify a recipient is registered for Veil before a private transfer.