# MCP server

`@quitanza/mcp` is a Model Context Protocol server over stdio that gives any MCP-capable agent direct access to Quitanza settlement: Claude Code, Claude Desktop, or your own. It speaks JSON-RPC 2.0, has zero dependencies beyond the Quitanza SDK, and exposes exactly five tools.

## The five tools

| Tool | What it does |
|---|---|
| `create_escrow` | Create an escrow between two sandbox agents (created for you) and lock simulated funds. |
| `submit_delivery` | Submit the payee's deliverable; verification runs at once and a passing verdict settles with a quitanza. |
| `check_status` | Fetch an escrow's state, verdicts, and deadline. |
| `open_dispute` | Open a structured challenge on a delivered escrow. |
| `get_quitanza` | Fetch and verify the settlement proof for a closed escrow. |

## Setup

Run the Quitanza API first:

```
pnpm --filter @quitanza/api dev    # http://localhost:4280
```

### Claude Code

```
claude mcp add quitanza -- pnpm --dir <path-to-repo>/quitanza --filter @quitanza/mcp dev
```

Or in `.mcp.json` at your project root:

```json
{
  "mcpServers": {
    "quitanza": {
      "command": "pnpm",
      "args": ["--dir", "<path-to-repo>/quitanza", "--filter", "@quitanza/mcp", "dev"],
      "env": { "QUITANZA_API_URL": "http://localhost:4280" }
    }
  }
}
```

### Claude Desktop

In `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "quitanza": {
      "command": "pnpm",
      "args": ["--dir", "<path-to-repo>/quitanza", "--filter", "@quitanza/mcp", "dev"],
      "env": { "QUITANZA_API_URL": "http://localhost:4280" }
    }
  }
}
```

`QUITANZA_API_URL` defaults to `http://localhost:4280`; point it elsewhere to use a different API instance.

## A session, end to end

Ask the agent to create a 25.00 USDC escrow for a research report. It calls `create_escrow`, receives the escrow and both agent ids, and hands the work over. When the deliverable is ready it calls `submit_delivery`; the engine verifies against the Terms and, on a pass, the response already carries the quitanza. `get_quitanza` re-verifies the proof at any later time: signature, trail integrity, trail head.

Local sandbox only: funds are simulated, keys are held server-side for convenience, and nothing leaves your machine.