> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veil.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Expose Veil as agent tools with the @veil-cash/mcp server

[`@veil-cash/mcp`](https://www.npmjs.com/package/@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:

```json theme={null}
{
  "mcpServers": {
    "base-mcp": { "url": "https://mcp.base.org" },
    "veil": {
      "command": "npx",
      "args": ["-y", "@veil-cash/mcp"]
    }
  }
}
```

<Tip>
  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.
</Tip>

### Hermes Agent

[Hermes Agent](https://hermes-agent.nousresearch.com) users can add Veil MCP as a stdio server in `config.yaml`:

```yaml theme={null}
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`):

```json theme={null}
{
  "mcpServers": {
    "veil": {
      "command": "npx",
      "args": ["-y", "@veil-cash/mcp"],
      "env": {
        "VEIL_KEY": "0x...",
        "RPC_URL": "https://your-base-rpc"
      }
    }
  }
}
```

<Info>
  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.
</Info>

## Tools

| Tool                       | Purpose                                                     |
| -------------------------- | ----------------------------------------------------------- |
| `veil_init_keypair`        | Generate and save a random local Veil keypair               |
| `veil_status`              | Check key, relay, wallet, and registration status           |
| `veil_get_balances`        | Read wallet, queue, and private balances                    |
| `veil_deposit_status`      | Check one queued deposit by pool and nonce                  |
| `veil_wait_for_deposit`    | Poll a queued deposit until accepted/rejected/refunded      |
| `veil_prepare_register`    | Return Base `send_calls` calldata for registration          |
| `veil_prepare_deposit`     | Return Base `send_calls` calldata for ETH/USDC deposits     |
| `veil_withdraw`            | Submit a private withdrawal through the Veil relay          |
| `veil_transfer`            | Submit a private transfer through the Veil relay            |
| `veil_consolidate_utxos`   | Merge fragmented private UTXOs into fewer notes             |
| `veil_pay_x402`            | Pay an x402 resource from private USDC via any facilitator  |
| `veil_x402_quote`          | Probe an x402 resource for price/requirement without paying |
| `veil_x402_receipts`       | List local x402 spend history and total USDC spent          |
| `veil_x402_payer_balances` | Inspect USDC left on deterministic x402 payer EOAs          |
| `veil_subaccount_status`   | Read 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:

```json theme={null}
{
  "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](/intro/verified-users/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](/intro/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](/build-with-veil/private-x402) page. Heavy x402 usage can fragment private UTXOs; when `veil_get_balances` reports `needsConsolidation`, call `veil_consolidate_utxos` to merge notes.

## Safety

<Warning>
  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.
</Warning>