Get Started
View as Markdown Open in ChatGPT Open in Claude

Developer tools

The Gravv CLI runs API calls from your terminal, and the Gravv MCP server connects your AI assistant to the API. Learn what each one does and how to use them together.

Gravv has two tools for building and testing your integration. Both call the same API as your own code, with your own API key.

  • The Gravv CLI is a gravv command for your terminal. It runs real API calls, prints each one as a curl command, and can run a whole sandbox flow with one command.
  • The Gravv MCP server connects an AI assistant, such as Claude, Cursor or VS Code with GitHub Copilot, to the Gravv API and these docs. You ask in plain words, and the assistant makes the calls.

Example. You want to see how a payout to a Nigerian bank account works before you write any code. You run gravv try payout-ng --curl. The CLI makes a test customer and a wallet, puts 20 test USDC in the wallet, adds a Nigerian bank payee and sends it 5.00 USD. It prints every call it made as curl. Then you ask your assistant to "write this payout flow in TypeScript". It reads the same docs pages through the MCP server and writes the code with the same calls.

Which tool to use

You want to Use
See a whole flow work in sandbox before you write code The CLI: gravv try
Copy a working request into your code The CLI with --curl
See why a call failed and how to fix it The CLI prints the error, the request id and the fix
Watch the webhooks Gravv sends you The CLI: gravv webhooks tail
Ask questions about the API in plain words The MCP server
Have your assistant write or fix your integration code The MCP server
Have your assistant run calls for you, such as onboarding a test customer The MCP server

What you need

  • A sandbox API key. It starts with grvSec_sandbox_. See Authentication.
  • For the CLI, macOS or Linux.
  • For the MCP server, Node.js 20 or later and an MCP client.

Sandbox and live use one host, https://api.gravv.xyz. Your key decides which one a call reaches. Both tools read the key's prefix and treat any key that does not start with grvSec_sandbox_ as live.

Set up the CLI

  1. Install it:

    curl -fsSL https://get.gravv.xyz | sh

  2. Save your key. The CLI checks the key with Gravv before it saves it:

    gravv init

  3. Check that everything is ready:

    gravv doctor

  4. Run your first flow:

    gravv try wallet --curl

    The CLI prints one line for each step, with the ids it made, and every call as curl.

The Gravv CLI page lists every journey and the commands you will use most.

Set up the MCP server

  1. Add the server to your client. In Claude Code:

    claude mcp add gravv --env GRAVV_API_KEY=<SANDBOX_API_KEY> -- npx -y @gravv-infra/mcp

    The Gravv MCP server page has the setup for VS Code, Cursor, Codex, Claude Desktop, Windsurf, Cline and Zed.

  2. Restart your client, then ask "What Gravv accounts do I have?". The assistant calls listAccountsV2 and answers with your sandbox data.

  3. Ask for what you need. For example:

    • "Onboard a test customer called Ada Lovelace and start her KYC."
    • "Search the Gravv docs for how to pay a Kenyan mobile money wallet."
    • "Write a TypeScript function that creates a payee and waits until it is active."
    • "Why did my last transfer fail?"

Without a key, the server starts in docs-only mode. The assistant can search and read these docs, but it cannot call the API.

How both tools keep you safe

  • You approve money movement. With the MCP server, a call that moves money returns a preview first. It runs only after you agree. With the CLI on a live key, a command that moves money runs only with --live, and then asks you to confirm.
  • Simulators stay in sandbox. Both tools refuse a simulator call with a key that is not a sandbox key, before they send anything.
  • Your key stays private. Neither tool prints or logs your key. A curl command from the CLI shows $GRAVV_SANDBOX_KEY in its place.
  • Card details stay hidden. Neither tool returns a card number, CVV or PIN. Use the client-side decryption flow.

Build your integration with both

  1. Run the flow you need with the CLI, such as gravv try payout-ng --curl, and keep the curl it prints.
  2. Ask your assistant to write the same flow in your language. Give it the curl so it uses the same fields.
  3. Run your code against sandbox. When a call fails, read the error guide, or ask the assistant what the error means.
  4. Run gravv webhooks tail to see the webhooks your code causes, and check that your server handles each one.
  5. When sandbox works end to end, follow the onboarding checklist to go live.
Was this page helpful?