---
name: sundaedb-connect
description: Install Coinbase Payments MCP and SundaeDB MCP on the user's machine. Usage and troubleshooting are in SundaeDB MCP server instructions after connect.
---

# Connect SundaeDB

If the user pasted **Add SundaeDB to my agent: sundaedb.com/SKILL.md** (or asked you to follow this document), set up SundaeDB and payments on **their machine** — the one where their agent client runs.

**This doc vs MCP instructions:** This file is **install and connect only**. After both MCP servers are configured, usage (semantic SQL, paid HTTP shape, troubleshooting) lives in **SundaeDB MCP server instructions** on every connection to `https://sundaedb.com/mcp`. Do not duplicate that material here.

## Before you start

Show the user this checklist and wait for confirmation:

```
Here's what I'll do to connect SundaeDB.

1. Install Coinbase Payments MCP (paid HTTP API + wallet on Base)
2. Add the SundaeDB MCP endpoint (https://sundaedb.com/mcp)
3. Have you restart or reload MCP in your client
4. Help you fund the wallet and set an agent session spending limit if needed

You'll need Node.js/npm on this machine and permission to edit MCP config or run terminal commands.

Shall I proceed?
```

## Prerequisites

- **Node.js and npm** on the user's machine (for `npx @coinbase/payments-mcp`).
- **MCP-capable agent client** (Cursor, Claude Code, Claude Desktop, Codex, Gemini CLI, or similar).
- Do not store wallet secrets or API keys in the project repo.

## Step 1 — Install Payments MCP

Detect which client the user is in (ask if unclear), then run the matching non-interactive install from the project root or home directory:

**Claude Code:**

```bash
npx -y @coinbase/payments-mcp install --client claude-code --auto-config
```

**Claude Desktop:**

```bash
npx -y @coinbase/payments-mcp install --client claude --auto-config
```

**OpenAI Codex CLI:**

```bash
npx -y @coinbase/payments-mcp install --client codex --auto-config
```

**Google Gemini CLI:**

```bash
npx -y @coinbase/payments-mcp install --client gemini --auto-config
```

**Cursor, VS Code, or other HTTP/stdio MCP clients:**

```bash
npx -y @coinbase/payments-mcp install --client other --no-auto-config
```

Then merge the Payments MCP stdio server into the user's MCP config without removing existing servers. Typical entry (use the path printed by the installer, often `~/.payments-mcp/bundle.js`):

```json
"payments-mcp": {
  "command": "node",
  "args": ["/ABSOLUTE/PATH/TO/.payments-mcp/bundle.js"]
}
```

For **Cursor**, add this under `mcpServers` in `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project).

If install fails, run `npx @coinbase/payments-mcp status` and see the [Payments MCP README](https://github.com/coinbase/payments-mcp).

## Step 2 — Add SundaeDB MCP

Endpoint URL (always HTTPS):

```text
https://sundaedb.com/mcp
```

Use **`https://sundaedb.com/mcp`** only (not localhost unless the user is developing SundaeDB itself).

**Cursor** — add alongside Payments MCP in the same `mcp.json`:

```json
"sundaedb": {
  "url": "https://sundaedb.com/mcp"
}
```

**Claude Code:**

```bash
claude mcp add --transport http sundaedb https://sundaedb.com/mcp
```

**Claude Desktop** — **Settings → Connectors → Add custom connector**:

```text
Name: SundaeDB
URL:  https://sundaedb.com/mcp
```

**Other JSON-based clients** — add an HTTP MCP server pointing at the URL above. Example shape:

```json
"mcpServers": {
  "sundaedb": { "url": "https://sundaedb.com/mcp" }
}
```

Never commit MCP config containing secrets; `.cursor/mcp.json` is often gitignored locally.

## Step 3 — Restart the client

Reload MCP or fully restart the agent application so **both** `payments-mcp` and `sundaedb` appear. Confirm in the client's MCP or connector list before paid work.

## Step 4 — Fund the wallet and session limit

Paid calls require USDC on Base. Use Payments MCP wallet/onramp tools (or the flow in [Coinbase Payments MCP](https://docs.cdp.coinbase.com/payments-mcp/welcome)) so the user can fund with card, Apple Pay, or transfer. Do not proceed with paid calls until the user accepts funding if the wallet is empty.

In the wallet app, set an **agent / AI session spending limit** high enough for metered queries (e.g. **$10+** for demos). If paid calls fail before SundaeDB responds, see **SundaeDB MCP server instructions** (session limit vs wallet balance).

## Step 5 — Verify (smoke)

Ask the user for US billing jurisdiction before paid steps (details in MCP instructions after connect).

With user approval, run a minimal smoke using **SundaeDB MCP server instructions** for exact Payments MCP fields and HTTP headers:

1. Paid HTTP **`POST /api/provision_sandbox`** (Payments MCP `make_http_request_with_x402`).
2. Paid HTTP **`POST /api/run_query`** with a trivial SQL body (e.g. `SELECT 1`). It returns right away with `status: running` and a `result_run_id`; the query runs and is billed in the background.
3. Free MCP **`wait_for_result`** with the `database_id`, `result_run_id`, and `result_schema` from step 2. Call it again while it reports `running`. The final report carries `table_name`, `amount_paid_usd`, and `tx_hash`.
4. Free MCP **`read_table_rows`** on the `table_name` from step 3.

**Never re-send a paid request to find out whether it finished.** Each send starts and bills a new run; use `wait_for_result` instead. Paid `run_query` and `create_embeddings` over HTTP always work this way. Paid MCP tools (x402 inside MCP) stay synchronous.

Optional: MCP **`provision_sandbox`** only if the user confirms their client handles MCP x402 retries on tool calls.

## Step 6 — First query

Suggest the user try:

```text
Create a SundaeDB sandbox, load https://sundaedb.com/test_data/movie_reviews.csv, and find the reviews that complain most often about the ending.
```

## After connect

All product usage, paid HTTP routes, and troubleshooting are in **SundaeDB MCP server instructions** when connected to `https://sundaedb.com/mcp`. Pricing for humans: [sundaedb.com/#pricing](https://sundaedb.com/index.html#pricing).

Docs: [SundaeDB](https://sundaedb.com/) · [x402](https://www.x402.org/) · [Payments MCP](https://github.com/coinbase/payments-mcp)