Connect Claude Desktop

Coming next. The MCP server runs on the sandbox today (fake rails, no money moves). Nothing is live in production yet.

TatvaPay's MCP server gives an assistant 17 tools: discover (find_seller, get_quote, get_forex_rates), buy (accept_quote, pay_intent, get_payment_status, get_receipt, verify_receipt), sell (create_quote, list_payments, issue_refund), mandates (list_my_mandates, request_mandate) and forex (forex_quote, upload_document, submit_file, file_status).

The assistant acts as one agent passport of your workspace. It can do what that agent can do, inside its mandates, and nothing more. It can never approve a payment, authorise a mandate or book a forex deal: when a person is needed, the tool answers requires_approval with a link to the app.

Option 1: Claude Desktop over stdio

Claude Desktop starts a small local bridge that signs every request with your agent's private key. The key never leaves your computer.

1. Make a sandbox API key and register a buyer agent (see the quickstart); save its private key as a .jwk.json file.
2. Authorise a mandate for that agent.
3. Add this to claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit config) and restart Claude Desktop:

{
  "mcpServers": {
    "tatvapay": {
      "command": "uv",
      "args": ["--directory", "/path/to/tatvapay-backend", "run", "python", "-m", "app.mcp_server", "--stdio"],
      "env": {
        "TATVAPAY_API_URL": "http://localhost:8100",
        "TATVAPAY_API_KEY": "tpk_…",
        "TATVAPAY_AGENT_ID": "agt_…",
        "TATVAPAY_AGENT_KEY": "/path/to/buyer.jwk.json"
      }
    }
  }
}

4. Ask Claude: "Find a travel seller on TatvaPay and buy me an airport transfer. Show me the receipt and check that it verifies."

The Developers → MCP and assistants page in the app has this snippet ready to copy.

Option 2: a remote connection with OAuth

Assistants that support remote MCP servers connect to the server URL shown in Developers → MCP and assistants. They register themselves, then send you to TatvaPay's consent screen, where you pick:

• the workspace and the agent passport the assistant will act as;
• what it may do: pay.read, pay.buy, pay.sell, mandates.request, forex.

This is OAuth 2.1 with PKCE (S256). Access tokens last an hour; refresh tokens rotate on every use, and a reused one ends the connection. Every connection is listed in the consent centre, where you revoke it in one tap.

What Claude sees

See error codes and rule ids.