Skip to main content
Glama
@gravv/mcp

@gravv/mcp

Official

@gravv-infra/mcp

MCP server for the Gravv payments API. Connects an AI assistant to Gravv so it can onboard customers, run KYC, open accounts, add recipients, move money, issue cards, and exchange currency — using your own API key.

Works with Claude, Cursor, VS Code, and any MCP-compatible client.


Quick start

Requires Node.js 20 or later. Check with node --version.

GRAVV_API_KEY=grvSec_sandbox_... npx @gravv-infra/mcp

Get an API key from your Gravv dashboard. Start with a sandbox key — the key itself decides which environment you reach.

To confirm it's wired up, ask your assistant:

What Gravv accounts do I have?

It should call listAccountsV2 and come back with real data. If you have no accounts yet, try "Search the Gravv docs for how to open an account" — the documentation tools work even before you have any.

Any MCP-compatible client works — the server speaks stdio and negotiates protocol version 2025-06-18, falling back to 2024-11-05 for older clients.

claude mcp add gravv --env GRAVV_API_KEY=grvSec_sandbox_... -- npx -y @gravv-infra/mcp

VS Code uses servers, not mcpServers, and requires an explicit type. Put this in .vscode/mcp.json to share with your team, or run MCP: Open User Configuration for a personal one:

{
  "servers": {
    "gravv": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gravv-infra/mcp"],
      "env": { "GRAVV_API_KEY": "grvSec_sandbox_..." }
    }
  }
}

Or from the CLI:

code --add-mcp '{"name":"gravv","command":"npx","args":["-y","@gravv-infra/mcp"],"env":{"GRAVV_API_KEY":"grvSec_sandbox_..."}}'
codex mcp add gravv --env GRAVV_API_KEY=grvSec_sandbox_... -- npx -y @gravv-infra/mcp

Or in ~/.codex/config.toml:

[mcp_servers.gravv]
command = "npx"
args = ["-y", "@gravv-infra/mcp"]

[mcp_servers.gravv.env]
GRAVV_API_KEY = "grvSec_sandbox_..."

Verify with codex mcp list.

These use the mcpServers shape:

{
  "mcpServers": {
    "gravv": {
      "command": "npx",
      "args": ["-y", "@gravv-infra/mcp"],
      "env": { "GRAVV_API_KEY": "grvSec_sandbox_..." }
    }
  }
}

Client

Config file

Claude Desktop

claude_desktop_config.json (Settings → Developer → Edit Config)

Cursor

~/.cursor/mcp.json, or .cursor/mcp.json per project

Windsurf

~/.codeium/windsurf/mcp_config.json

Cline

the MCP Servers panel, or cline_mcp_settings.json

Zed

settings.json under context_servers

The server is a plain stdio MCP process. Point any client at:

command: npx
args:    ["-y", "@gravv-infra/mcp"]
env:     GRAVV_API_KEY=grvSec_sandbox_...

To try it without a client:

GRAVV_API_KEY=grvSec_sandbox_... npx -y @gravv-infra/mcp

then paste a JSON-RPC frame on stdin:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1"}}}

Keep the key out of source control. Several clients support environment-variable substitution or secret prompts — prefer those over pasting a live key into a file you might commit. A sandbox key is the right thing to start with either way.


Related MCP server: M-Pesa MCP Server

What you get

Documentation tools — searchGravvDocs and getGravvDocPage search every page of the Gravv documentation, read from the docs site as it is published. They need no API key, so you can explore Gravv before you have credentials.

API tools — 90 tools, all loaded by default (88 on a live key, which hides the two sandbox simulators), covering customers, KYC, accounts, transfers, limits, cards, wallets, savings, FX and settlement instructions, collections, webhooks, and sandbox deposit and savings interest simulators.

Prompts — eleven goal prompts, from opening an account to unsticking a transfer. Pick one in your client and the assistant gets the questions to ask first, the tool order for each path, the confirm steps and the recovery rules (Prompts).

Both matter. The API tools execute calls, but they can't tell you what has to happen first — that an account needs a KYC-verified customer, or that a new recipient must reach active before you can pay them. That's what the guides are for, so they're reachable from the same connector. Ask the assistant how to do something and it can look it up, write your integration, then run it against sandbox to prove it works.

npx @gravv-infra/mcp     # with GRAVV_API_KEY: docs + API tools + prompts
npx @gravv-infra/mcp     # without it: docs tools and prompts, still useful

Prompts

MCP prompts are chosen by the user, not the model: your client lists them (often behind / or a prompt menu). Each one is a whole goal, built from Gravv's integration scenarios. It says what to ask the user before any call, gives each path's tool order with its confirm steps and recovery, links the docs page to read, and ends with the rules every task shares: never invent a value, confirm before money moves, and when to resend with the same idempotency_key and when to leave it out.

Prompt

For

Optional argument

open-account

a bank account or the business's card account; an application the bank is waiting on; deposit details

path: v2, card-account, manage

onboard-customer

create and verify a person or a business; resubmit; read KYC documents

path: person-hosted, person-s2s, business, resubmit, documents

send-payout

ACH, wire, RTP, SWIFT, SEPA, Faster Payments, or between own accounts

rail: ach, wire, rtp, swift, sepa, fps, book

send-remittance

a bank account or mobile wallet abroad, in about 60 countries

country: NG, GH, KE, RW, ZM, UG, CG, CI, BJ, MX, BR, CO, IN, HK, or xof

send-crypto

USDC or USDT to a wallet; USDT to USDC between own wallets

path: same-network, cross-network, convert

convert-currency

quote and place an FX order; settlement instructions; follow or cancel

path: quote-and-order, settlement-instruction, manage

issue-card

verify a cardholder and issue a card; fund, limit, freeze, close

path: hosted-kyc, own-kyc, fund, limit, freeze-or-block, close, another-card

collect-payment

stablecoin deposits, bank deposits, bank transfers, card checkout, saved cards

method: stablecoin, bank-deposit, bank-transfer, card, saved-card

set-up-savings

open a savings account, save and withdraw, interest and statements, test it in sandbox

path: open, move, read, test

reconcile

transactions against the books, one transfer's webhooks, fees, missed events

path: transactions, trace, fees, webhooks

fix-stuck-transfer

pending, paused, under review or failed, and how to answer a pause

transaction_id

The argument narrows the prompt to one path; leave it out to get them all. Route availability follows the docs: a route is Available, Not yet available (ask support to switch it on for your business), or Not supported. A prompt names any tool it uses that the session has not loaded (a toolset left out of --toolsets, or simulateDeposit and simulateSavingsInterest, which need a sandbox key), and says so when there is no API key.

Next steps and fix hints. Results carry the same knowledge where a call answers. A 200 that is not done, such as a paused transfer, a declined card or a file the card KYC refused, comes back with next_step ahead of data. A 4xx the scenarios name, such as a duplicate payee, a closed route or an expired FX quote, gets a hint that says what to do instead of what the status means.


Safety model

Gravv moves real money, and sandbox and live share one base URL — only your key differs. Nothing in a request visually signals danger, so the server signals it.

Money-moving tools take two calls. createTransfer, resumeTransfer, withdrawFromCard, createFxOrder, cancelFxOrder, createCollection, createCardPaymentIntent, and chargeSavedCard return a preview on the first call and execute only when called again with confirm: true. The unconfirmed call never reaches the API. resumeTransfer is included because resuming a paused transfer releases the payout.

cancelFxOrder is included because a cancel cannot be undone: funds already debited are not returned. createCardPaymentIntent is included because, given a saved card_token, it charges the card at once; it asks for confirmation even when it only makes a link.

> Send $50 from acc_1 to acc_2

  createTransfer({ amount: 50, ... })
  -> { status: "confirmation_required",
       willDo: "Transfer 50 USD from acc_1 to internal_account acc_2.
                Once submitted this cannot be reversed from the API." }

  [assistant shows this to you, you agree]

  createTransfer({ amount: 50, ..., confirm: true })
  -> { data: { transfer_id: "trf_1", status: "pending" } }

Tools that cannot be undone take two calls too. deleteSavedCard, deleteSettlementInstruction and activateFeature (which can issue a card) return a preview first and run only with confirm: true. They move no money, so they do not need GRAVV_ALLOW_LIVE_WRITES.

Sandbox-only tools stay in sandbox. simulateDeposit and simulateSavingsInterest are listed and run only with a grvSec_sandbox_ key. On any other key they are hidden, and a call by name is refused before any request.

Files stay out of the conversation. Upload tools take a local file_path: the server reads the file, checks its type from its first bytes and its size, and sends it, so the assistant never handles the base64. downloadCustomerKycDocument saves the image to a local file (mode 0600, in a 0700 folder) and returns only its path, type and size. Set the folder with GRAVV_DOWNLOAD_DIR or --download-dir; by default it is gravv-mcp-downloads in the system temp folder.

A live key needs a second independent signal. Money movement on a grvSec_live_ key is refused unless GRAVV_ALLOW_LIVE_WRITES=true is also set. Confirmation alone is not enough. An unrecognised key format is treated as live — it fails closed.

Cardholder data is never exposed. The endpoints returning card PAN, CVV, and PIN are not registered as tools under any configuration, and responses are scanned for card_number / cvv / pin and redacted on the way out. Use the client-side decryption flow for those.

Idempotency is automatic, and a call can be resent under its key. Every write that needs an Idempotency-Key gets one — a new key for every call — and the key is returned with every result, successful or not. When a call times out, hits a network error or gets a 5xx, nobody knows yet whether it took effect: the result says outcome_unknown, and its hint names the tool that shows whether it did. Look first. If nothing happened, call again with the same arguments plus that result's idempotency_key; if the first call did land in the meantime, the API returns its answer instead of running it twice. After any other 4xx, call again without idempotency_key: the gateway keeps a 4xx answer under its key for 24 hours, so the same key only gets that answer back. A write the gateway rate-limits is retried for you under a new key, which is safe because that request never ran; a key you passed yourself is never swapped, so that 429 comes back to you with a hint to look first.

--read-only disables every non-GET tool, for reporting deployments.


Toolsets

Every toolset loads by default. Name some with --toolsets to load only those.

npx @gravv-infra/mcp                                       # default
npx @gravv-infra/mcp --toolsets=customers,accounts,cards   # specific groups
npx @gravv-infra/mcp --toolsets=all                        # everything

Toolset

Default

Covers

customers

✓

create, list, get, update customers

accounts

✓

capabilities, v2 accounts and their applications, and the business's one card account

transfers

✓

transfers, supporting documents, resume, limits, rate-locked quotes, rates, supported countries and currencies

transactions

✓

history, volume, export

external-accounts

✓

recipients, verification, institutions

kyc

✓

KYC start, server-to-server, document upload and download, status

cards

✓

issue, balance, status, withdraw, applications, card KYC, feature activation

wallets

✓

blockchain wallet creation and lookup

savings

✓

a customer's savings, the savings rate and daily statements (sandbox only for now)

fx

✓

quotes, rates, OTC orders, settlement instructions

collections

✓

card payment intents, saved cards, and bank transfer collections

webhooks

✓

event history, delivery calls, retry

sandbox

✓

the deposit and savings interest simulators (sandbox keys only)

The approvals and payment-links toolsets were removed in 0.3.2, and account-applications in 0.4.0. A configuration that still names them starts with a warning, and those names are ignored. The features toolset merged into cards in 0.4.0: --toolsets=features loads cards, with a warning.


Tool reference

* marks a tool that moves money and therefore requires confirm: true. † marks a tool that cannot be undone and also requires confirm: true.

Documentation — always available, no API key needed searchGravvDocs · getGravvDocPage

customers createCustomer · getCustomer · listCustomers · updateCustomer

kyc startCustomerKyc · startCustomerKycS2S · uploadCustomerKycDocument · getCustomerKycDocuments · downloadCustomerKycDocument · getCustomerKycStatus

accounts getAccountCapabilities · getAccountRequirements · createAccountV2 · getAccountV2 · listAccountsV2 · getAccountApplicationV2 · listAccountApplicationsV2 · updateAccountApplicationV2 · createAccount · getAccount · listAccounts

Accounts are opened with createAccountV2, after getAccountCapabilities and getAccountRequirements. The one exception is your business's card account, which backs every card you issue: v2 cannot open a working card account yet, so createAccount, getAccount and listAccounts are kept for that one account only. Accounts and wallets take five networks: polygon, ethereum, solana, stellar and Avalanche (avalanche_c_chain on accounts, avalanche on wallets).

external-accounts — recipients you pay out to createExternalAccount · getExternalAccount · listExternalAccounts · updateExternalAccount · verifyExternalAccount · listExternalAccountInstitutions · verifyWireRoutingNumber · verifyRtpRoutingNumber

transfers createTransfer* · uploadTransferDocument · resumeTransfer* · getCustomerLimits · getRemitterLimits · getTransferQuote · getTransferRates · listTransferSupportedCurrencies · listTransferSupportedCountries · listTransferSupportedCountriesForAddress

transactions listTransactions · getTransaction · getTransactionsVolume · exportTransactions

cards createCard · getCard · listCards · getCardBalance · updateCardStatus · withdrawFromCard* · createCardApplication · getCardApplication · listCardApplications · startCardholderKyc · startCardholderKycS2S · uploadCardholderKycDocument · listFeatures · checkFeatureEligibility · activateFeature†

Card KYC (startCardholderKyc and the server-to-server pair) verifies a cardholder for card issuance, with a liveness check. It is separate from a customer's own KYC in kyc. In live, a card is issued with activateFeature and feature_id: virtual_cards.

wallets createWallet · getWallet · listWallets

savings — saving and withdrawing are createTransfer* getSavingsRate · getSavings · getSavingsStatement

fx getFxQuote · listFxRates · listFxCurrencyPairs · createFxOrder* · getFxOrder · listFxOrders · cancelFxOrder* · listFxPendingApprovals · listSettlementInstructions · createSettlementInstruction · getSettlementInstruction · updateSettlementInstruction · deleteSettlementInstruction†

collections — taking money in

Card payments go through createCardPaymentIntent. It returns the same hosted payment link as a collection, plus the intent id and the card token that recurring and merchant-initiated charges need. createCollection covers bank transfer, in 16 countries.

createCardPaymentIntent* · chargeSavedCard* · listSavedCards · getSavedCard · deleteSavedCard† · createCollection* · getCollection

webhooks getWebhookHistory · getWebhookEventDetail · getWebhookCallHistory · retryWebhookEvent

sandbox — sandbox keys only simulateDeposit · simulateSavingsInterest

Each tool's description carries its own prerequisites — several operations depend on something else having happened first, and the assistant reads those before calling.


A worked example

Asking an assistant to "pay our US supplier 1,250 USD by ACH from my main account":

1. searchGravvDocs("pay a US bank account by ACH")
   -> finds the bank payouts guide, learns the recipient must be `active`
      before a transfer will succeed

2. getAccountV2({ account_id })
   -> confirms the USD account is funded

3. listExternalAccounts({ customer_id, search: "<account number>" })
   -> no payee for this account yet, so one is added

4. createExternalAccount({ payee_type: "ach_wire", payment_rail: "ach", ... })
   -> an ach_wire payee comes back "pending"

5. getExternalAccount({ external_account_id })
   -> polled until "active" (or "setup_failed", which next_step explains)

6. createTransfer({ amount: "1250.00", source, destination, client_reference })
   -> returns a PREVIEW, does not execute:
      "Transfer 1250.00 USD from acc_1 to external_account ext_9.
       Once submitted this cannot be reversed from the API."

   [you review and agree]

7. createTransfer({ ...same arguments, confirm: true })
   -> executes; returns the transaction and transfer_status

Step 1 is what stops step 6 failing. Without the guides, an assistant tends to create the recipient and immediately transfer to it, before the payment rail has finished setting them up. The send-payout prompt with rail: ach walks the same path.


Going live

  1. Test the whole flow with your sandbox key first. Sandbox and live hold entirely separate data — an id from one does not exist in the other.

  2. Swap GRAVV_API_KEY for your live key. The base URL does not change.

  3. Reads and non-financial writes work immediately.

  4. Money movement stays blocked until you also set GRAVV_ALLOW_LIVE_WRITES=true. This is deliberate: swapping the key alone should not silently arm real payments.

{
  "mcpServers": {
    "gravv": {
      "command": "npx",
      "args": ["-y", "@gravv-infra/mcp"],
      "env": {
        "GRAVV_API_KEY": "grvSec_live_...",
        "GRAVV_ALLOW_LIVE_WRITES": "true"
      }
    }
  }
}

Consider a second, separate entry running --read-only against your live key for reporting, and keep writes on sandbox.


Troubleshooting

The server doesn't start Check node --version is 20 or later. Without GRAVV_API_KEY the server still starts, but only the two documentation tools load — that's expected, not a failure.

401 on every call The key was rejected. Confirm it is current and that you copied the whole value.

404 on an id you know exists You're probably in the other environment. Sandbox and live hold separate data. The environment field in every result, and the ENVIRONMENT line of the server instructions, tell you which one you're in.

"tool exists but its toolset is not loaded" Restart with --toolsets=all, or name the group the error mentions.

"Not available over MCP" on card PAN, CVV, or PIN Intentional and not configurable. Use the client-side decryption flow.

A transfer returned confirmation_required instead of running Working as designed. Call again with confirm: true after reviewing the preview.

"Not available over MCP" for an approve or reject tool, a payment-link tool, or a simulator Approving and rejecting is done in the Gravv Dashboard, and payment links are retired (both since 0.3.2). The card and collection sandbox simulators are not offered yet. The message says what to do instead. deleteSavedCard is back in 0.4.0.

"Renamed" for startRiskKyc, startRiskKycS2S or uploadRiskDocument Card KYC returned in 0.4.0 as startCardholderKyc, startCardholderKycS2S and uploadCardholderKycDocument, in the cards toolset.

"Removed in 0.4.0" for a v1 account application tool or updateAccountStatus The v1 account API left the docs. Accounts are opened with createAccountV2; the message names the tools to use.

simulateDeposit "is a sandbox-only test tool" It runs only with a grvSec_sandbox_ key. On a live key nothing is sent.

ignored_arguments in a result The tool does not take those arguments, so they were not sent. Check the field names in the tool's schema; a filter you meant to apply was not applied.

A grvPub_ key Publishable keys cannot call the API. Set GRAVV_API_KEY to a secret key starting grvSec_sandbox_ or grvSec_live_.

422 Not always about idempotency. A transfer over a sender limit, a blocked sender, missing sender information or a missing supporting document is also a 422; the error's code and the hint say which. A 422 with idempotency_key_reused means the same idempotency_key was sent before with a different body. If this is a resend, send exactly the same arguments as the first call. If it is a new request, leave idempotency_key out and a fresh key is made.

Repeated 429 The gateway allows 600 requests a minute, burst 50, per Gravv account, shared by every key and process. This server throttles itself to 60 a minute, so repeated 429s usually mean another process uses the same account. This server retries a POST with a new key (unless you passed the key yourself), so a 429 that persists has already been retried. Wait and try again.

A call timed out The result says outcome_unknown: true, and the call may have taken effect. Do not call again straight away: the hint names the tool that shows whether it did (for a transfer, listTransactions for the source account, matched on your client_reference). If nothing happened, call again with the same arguments plus the idempotency_key from the result.

409 after a resend If the hint says the first call is still running, wait a few seconds and resend with the same arguments and idempotency_key. A 409 saying the client_reference was already used for a different transfer is final: find the earlier transfer, and use a new client_reference only for a genuinely new payment.

413 on an upload The message can state a size the route does not take. Each upload tool takes files up to its own limit:

Tool

Largest file

uploadCustomerKycDocument

5 MB

uploadCardholderKycDocument

5 MB

uploadTransferDocument

700 KB

createAccountV2, updateAccountApplicationV2 documents

2 MB each

In sandbox, keep the files of one call under 500 KB together: larger requests are refused there, with a 413 that says 10MB. The hint names the tool's limit. An oversized card KYC file can also come back as a 400.

Documentation search returns nothing It's keyword-based, not semantic. Rephrase using the vocabulary the docs use — "transfer" rather than an unusual synonym — or drop the section filter.


Configuration

Variable

Default

Purpose

GRAVV_API_KEY

—

Sandbox or live key; selects the environment. Omit for docs-only mode

GRAVV_ALLOW_LIVE_WRITES

unset

true permits money movement on a live key

GRAVV_RATE_PER_MINUTE

60

Client-side request throttle

GRAVV_BASE_URL

https://api.gravv.xyz

Override the API host. Anything but https://api.gravv.xyz starts with a warning

GRAVV_TOOLSETS

default set

Same as --toolsets

GRAVV_DOCS_ORIGIN

https://gravv-docs.syntext.dev

Where the documentation tools read the docs. Same as --docs-origin

GRAVV_DOWNLOAD_DIR

gravv-mcp-downloads in the system temp folder

Where downloaded files are saved. Same as --download-dir

The documentation tools read the docs site's /llms.txt and /llms-full.txt. If the docs move, point GRAVV_DOCS_ORIGIN at the new address; the docs links the server returns follow it. If the site cannot be reached, the tools keep answering from the last copy they loaded, and say so.

The client throttles requests locally (60 a minute, burst 15) and backs off on 429. The gateway allows 600 a minute, burst 50, per Gravv account. See Rate limits.

Your API key is read from the environment and sent only to the Gravv API. It is never written to disk, logged, or included in tool output.


Notes

If a documentation search comes back empty, rephrase it. Search matches wording rather than meaning, so an unusual phrasing occasionally misses a page that does exist.

The Gravv CLI gives the same error fixes and money-moving rules as this server. It embeds data/gravv-shared.json, which npm run export-data writes from src/; a test fails when that file is out of date.


License

MIT — see LICENSE.

Available Tools

2 tools
getGravvDocPageA

Fetch the full text of one Gravv documentation page by slug, as returned by searchGravvDocs. Use when an excerpt is not enough — for worked examples, complete request/response bodies, or a full flow diagram.

Inputs: slug (required).

searchGravvDocsA

Search the Gravv documentation — integration guides, recipes, and API reference, every page the docs site lists. Use this BEFORE implementing any Gravv integration, and whenever a call fails in a way the error does not fully explain. The guides carry the ordering, prerequisites, and corridor rules that the API tool schemas do not. Returns ranked pages with excerpts; follow up with getGravvDocPage for full text.

Inputs: query (required), limit, section.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools form the classic search-then-fetch pair with clearly disjoint roles: one returns ranked excerpts across the docs corpus, the other returns full text for a single slug returned by the first. The descriptions explicitly state the handoff ("follow up with getGravvDocPage" / "by slug, as returned by searchGravvDocs"), leaving no room for misselection.

    Naming Consistency5/5

    Both names follow the same camelCase verb+noun pattern with a shared Gravv/Doc domain prefix: searchGravvDocs and getGravvDocPage. The verbs (search vs get) correctly signal breadth vs single-item retrieval, so the convention is both predictable and semantically informative.

    Tool Count4/5

    Two tools is thin relative to the 3-15 guideline, but for a pure documentation-retrieval server the search/fetch pair is the minimal complete surface and neither tool is redundant. Nothing is padded, though a third tool (e.g. list/index pages) would round it out.

    Completeness4/5

    Search plus full-page fetch covers the documentation lookup lifecycle end to end, including the excerpt-to-full-text escalation path. The only minor gap is the absence of any way to browse or enumerate page slugs or check docs versioning without a prior search hit.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for AgentPay — the payment gateway for autonomous AI agents. Fund a wallet once, give your agent the key, and it discovers, provisions, and pays for tool APIs on its own. One key, every tool.
      112 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      A local MCP server that lets AI agents interact with the Adaptis (MEG) payment gateway, enabling payment link creation, transaction queries, refunds, and integration helpers like generating signed forms and verifying callbacks.
      -