Skip to content
nuez docs

MCP Setup

Connection details

Section titled “Connection details”
FieldValue
URLhttps://sandbox-mcp.nuez.app/mcp
TransportStreamable HTTP, single POST endpoint (JSON-RPC 2.0)
AuthOAuth 2.1 (recommended) or Authorization: Bearer <api-key or JWT>
Rate limit30 tool calls/minute per user

It implements the Model Context Protocol over HTTP; any MCP client can connect to it. In this sandbox environment the MCP endpoint lives on its own host (sandbox-mcp.nuez.app), separate from the REST API host (sandbox-api.nuez.app) — the two aren’t interchangeable.

Section titled “Connect an interactive agent (OAuth, recommended)”

The MCP endpoint supports OAuth 2.1 with RFC 9728 protected-resource discovery. If your client sends a request without credentials, it gets back a 401 with a WWW-Authenticate: Bearer resource_metadata="https://sandbox-api.nuez.app/.well-known/oauth-protected-resource" header — any OAuth-aware MCP client (Claude Code, Cursor, Codex) follows that automatically: it fetches the metadata, discovers the authorization server, and opens a browser for you to log in. No token to copy or paste.

Terminal window
claude mcp add --transport http nuez https://sandbox-mcp.nuez.app/mcp

Then run /mcp inside Claude Code to complete the login. In Cursor, add the same URL to mcpServers with no headers field — it detects the OAuth requirement on its own. See Claude Desktop and Cursor for client-specific screenshots and config snippets.

Connect a programmatic agent (API key)

Section titled “Connect a programmatic agent (API key)”

If your agent can’t do an interactive browser login — a script, a backend service, a CI job — authenticate with an API key instead. See Authentication below and API keys.

Available tools

Section titled “Available tools”

Tools are grouped by domain. Card, bill, and crypto tools only appear in tools/list if the server has that feature enabled/configured.

GroupTools
Wallet & payoutsget_balance, get_cvu, list_recent_deposits, list_recent_payouts, get_payout_status, get_thresholds, request_payout, propose_threshold_change, list_pending_approvals, get_receipt
Cardsget_card_account_status, issue_card, list_cards, get_card, cancel_card, get_card_secure_token, fund_card_account, withdraw_card_account, list_card_transactions
Bill paymentssearch_bill_companies, get_bill, pay_bill, list_bill_payments, add_bill_to_whitelist, remove_bill_from_whitelist, list_bill_whitelist
Crypto off-rampget_crypto_status, get_crypto_addresses, get_crypto_balances, activate_crypto, set_auto_swap, get_crypto_offramp_quote, execute_crypto_offramp

Authentication

Section titled “Authentication”

The Authorization header accepts any of:

  • An OAuth access token issued after the discovery flow above — this is what an interactive MCP client uses once you’ve logged in.
  • Your raw API key (nz_...) — nuez detects the prefix and looks it up directly, no extra round-trip.
  • A JWT obtained from POST /v1/auth/token or POST /v1/login — same JWT you’d use for the REST API.

All three resolve to the same user and the same policy.

Raw JSON-RPC example

Section titled “Raw JSON-RPC example”
Terminal window
curl -X POST https://sandbox-mcp.nuez.app/mcp \
  -H "Authorization: Bearer nz_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": { "name": "get_balance", "arguments": {} }
  }'

Tool results come back as result.content[0].text — a JSON string you need to parse (or an "Error: ..." string with isError: true on failure).

Client-specific setup

Section titled “Client-specific setup”