# Grip MCP

> Give Claude (or any MCP-compatible agent) a non-custodial USDC wallet on Base — with human-in-the-loop approval on every payment.

## What this is

`@grip-foundation/grip-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that exposes four tools to any MCP-aware client (Claude Desktop, Claude Code, Continue, etc.):

| Tool | What it does | Who approves |
|---|---|---|
| `grip_wallet` | Returns the agent's smart account address + USDC balance on Base. | — |
| `grip_create_payment` | Stages a payment (off-chain). Returns an approval token. | — |
| `grip_settle_payment` | Settles or rejects a staged payment. On approve, executes a real USDC transfer on Base mainnet. | **Human, in chat** |
| `grip_list_payments` | Lists recent payments from the session. | — |

The agent never moves money without you. The flow is: agent stages → you confirm in chat → agent settles. There is no programmatic auto-approve.

## Install

### Option 1 — via `npx` (after first publish)

In `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "grip": {
      "command": "npx",
      "args": ["-y", "@grip-foundation/grip-mcp"]
    }
  }
}
```

### Option 2 — local clone

```bash
git clone https://github.com/grip-foundation/grip-mcp.git
cd grip-mcp
pnpm install
pnpm run build
```

Then point Claude Desktop at the built file:

```json
{
  "mcpServers": {
    "grip": {
      "command": "node",
      "args": ["/absolute/path/to/grip-mcp/dist/server/index.js"]
    }
  }
}
```

Restart Claude Desktop after editing the config.

## First run

The first time the server starts, it generates a brand-new EOA private key and stores it at `~/.grip-mcp/agent-key` (mode 0600). This key controls the smart account.

In Claude, ask:

> *Show me my Grip wallet*

Claude will call `grip_wallet` and reply with your smart account address, balance, and limits. Send USDC on Base to that address to fund.

## Making a payment

Once funded, ask Claude something like:

> *Send 5 USDC to 0xba14744FfD57FA7d03b20D4c8BeDAaC301E865d1*

Claude will:
1. Call `grip_create_payment` to stage the payment off-chain.
2. Show you the details (amount, recipient, memo) and ask for confirmation.
3. Wait for your reply.
4. If you say "approve" → call `grip_settle_payment(token, "approve")` → executes on Base.
5. If you say "no" → call `grip_settle_payment(token, "reject")` → no on-chain action.

Tx hash + Basescan link are returned on settlement.

## Configuration

| Env var | Default | What it does |
|---|---|---|
| `GRIP_MCP_PRIVATE_KEY` | (auto-generate) | Override the agent's signer private key. Useful for restoring a wallet across machines. |
| `GRIP_MCP_KEY_PATH` | `~/.grip-mcp/agent-key` | Where the auto-generated key is stored. |
| `GRIP_MCP_PER_TX_CAP` | `100` | Maximum USDC per single payment. |
| `GRIP_MCP_DAILY_CAP` | `500` | Maximum USDC across all payments per UTC day. |

## Security model

- **Non-custodial.** The Grip Foundation does not hold your keys, your USDC, or any record of your payments. Everything runs on your machine.
- **Managed paymaster, no signup.** Gas is paid in USDC via the Pimlico paymaster routed through Grip's hosted proxy. You don't need a Pimlico account.
- **Human-in-the-loop is enforced by the protocol, not the model.** `grip_create_payment` only stages. `grip_settle_payment` is a separate tool call. Most MCP clients (Claude Desktop included) prompt for human confirmation before executing tool calls — that's a second layer of gating.
- **Caps are enforced server-side.** Even if the model attempts a payment over your per-tx or daily cap, the server refuses to stage it.

## Architecture

```
Claude Desktop
     │ MCP (stdio)
     ▼
grip-mcp (this server)
     │ @grip-labs/sdk
     ▼
Grip-managed paymaster proxy → Pimlico bundler → Base mainnet
                                                       ▲
                                                  Coinbase Smart Wallet
                                                  (your smart account)
```

The smart account is a Coinbase Smart Wallet (ERC-4337) on Base. The first payment from a fresh wallet runs a one-time bootstrap UserOp that deploys the account and approves the paymaster for USDC reimbursement; subsequent UserOps are USDC-paid.

## Known issues

**First payment may need a retry.** In `@grip-labs/sdk@0.4`, the bootstrap UserOp (deploy + paymaster approve) and the actual transfer UserOp are submitted as two separate operations. There's a small race window where viem's internal `getFactoryArgs()` reads stale `getCode` from the public RPC after bootstrap has settled at the Pimlico bundler — viem then includes `initCode` in the second UserOp and the bundler rejects it with `AA10 sender already constructed`.

If your first payment fails with that error, simply ask the agent to retry. The retry succeeds because the on-chain state has propagated by then. Subsequent payments from the same wallet are clean — bootstrap runs at most once per wallet.

A fix is shipping in `@grip-labs/sdk@0.5` that consolidates bootstrap + first transfer into a single sponsored UserOp using `executeBatch`, eliminating the race by construction and saving ~30% gas on the first payment. `grip-mcp` will pick it up in `0.1.1`.

## License

MIT

## Built by

[Grip Foundation](https://gripprotocol.com) · open identity + payments rails for AI agents.