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

# MCP Server

> Connect Unwall to Claude, Cursor, and other MCP-compatible AI clients.

# MCP Server

The Unwall MCP server lets AI assistants like Claude, Cursor, and other MCP-compatible clients interact with your Unwall project directly -- checking balances, sending payments, and making x402 API calls through natural language.

## What Is MCP?

The **Model Context Protocol (MCP)** is an open standard that lets AI assistants use external tools. Instead of writing code to call APIs, your AI assistant can use MCP tools as native capabilities. For example, you can ask Claude "What's my wallet balance?" and it will call the `get_balance` tool automatically.

## Installation

No global install is needed. The MCP server runs via `npx`:

```bash theme={null}
npx @unwall/mcp-server
```

## Claude Desktop Configuration

Add the following to your Claude Desktop configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "unwall": {
      "command": "npx",
      "args": ["@unwall/mcp-server"],
      "env": {
        "UNWALL_API_KEY": "aw_live_your_key"
      }
    }
  }
}
```

<Tip>
  On macOS, the Claude Desktop config file is located at `~/Library/Application Support/Claude/claude_desktop_config.json`. On Windows, it is at `%APPDATA%\Claude\claude_desktop_config.json`.
</Tip>

## Cursor / VS Code

Add the MCP server in your editor's MCP settings. The configuration is the same JSON format:

```json theme={null}
{
  "mcpServers": {
    "unwall": {
      "command": "npx",
      "args": ["@unwall/mcp-server"],
      "env": {
        "UNWALL_API_KEY": "aw_live_your_key"
      }
    }
  }
}
```

## Available Tools

The MCP server exposes the following tools to your AI assistant:

| Tool                       | Description                   | API Equivalent               |
| -------------------------- | ----------------------------- | ---------------------------- |
| `get_balance`              | Check wallet balance          | `GET /v1/balance`            |
| `list_transactions`        | View transaction history      | `GET /v1/transactions`       |
| `pay`                      | Make a payment (any rail)     | `POST /v1/pay`               |
| `get_usdc_deposit_address` | Get funding address           | `GET /v1/stablecoin/address` |
| `send_payment`             | Send ACH payment (deprecated) | `POST /v1/payments`          |
| `x402_pay`                 | x402 API call (deprecated)    | `POST /v1/x402/pay`          |
| `send_usdc`                | USDC transfer (deprecated)    | `POST /v1/usdc/transfer`     |

<Note>
  The `pay` tool is the recommended way to make payments. It supports all three rails (x402, USDC transfer, fiat ACH) and auto-routes based on the recipient. The `send_payment`, `x402_pay`, and `send_usdc` tools are deprecated but still functional.
</Note>

## Environment Variables

| Variable          | Required | Default                  | Description                           |
| ----------------- | -------- | ------------------------ | ------------------------------------- |
| `UNWALL_API_KEY`  | Yes      | --                       | Your Unwall API token (`aw_live_...`) |
| `UNWALL_BASE_URL` | No       | `https://api.unwall.xyz` | API base URL (override for testing)   |

## Example Usage

Here is an example conversation with Claude using the Unwall MCP server:

<AccordionGroup>
  <Accordion title="Checking balance">
    **You:** What's my current wallet balance?

    **Claude:** Let me check your Unwall balance.

    *Uses `get_balance` tool*

    Your project has **5.00 USDC** available (\$5.00 USD equivalent) with no pending transactions.
  </Accordion>

  <Accordion title="Making an x402 payment">
    **You:** Fetch the latest market data from [https://api.example.com/v1/market](https://api.example.com/v1/market) using x402. Limit spending to 0.50 USDC.

    **Claude:** I'll fetch the market data using an x402 payment.

    *Uses `pay` tool with recipient "[https://api.example.com/v1/market](https://api.example.com/v1/market)" and max\_amount\_usdc 500000*

    The request completed successfully. The API charged 0.05 USDC plus a 0.001 USDC platform fee. Here's the market data:

    ```json theme={null}
    {"data": [{"symbol": "BTC", "price": 95420.50}, ...]}
    ```
  </Accordion>

  <Accordion title="Sending a USDC transfer">
    **You:** Send 10 USDC to 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 for the vendor invoice.

    **Claude:** I'll send 10 USDC to that address.

    *Uses `pay` tool with recipient "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18" and amount\_usd 10.00*

    Payment submitted. Transaction ID: `tx_abc123`. The transfer is processing on Base chain and should complete within a few minutes.
  </Accordion>
</AccordionGroup>

## Token Permissions

The MCP server inherits the permissions of the API token you provide. Make sure your token has the permissions your AI assistant needs:

| Action                           | Required Permission |
| -------------------------------- | ------------------- |
| Check balance, view transactions | `read`              |
| Send USDC or fiat payments       | `pay`               |
| Make x402 API calls              | `x402`              |

<Tip>
  For most use cases, create a token with all three permissions: `read`, `pay`, and `x402`. If your assistant only needs to monitor balances, a `read`-only token is sufficient and more secure.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Tokens" icon="key" href="/concepts/tokens">
    Learn about token permissions and security best practices.
  </Card>

  <Card title="x402 Protocol" icon="bolt" href="/guides/x402-payments">
    Deep dive into how x402 payments work under the hood.
  </Card>
</CardGroup>