@gravv/mcp
OfficialIn this schema, the server provides Gravv documentation search and page retrieval; the README describes broader API/payment capabilities when an API key loads the full toolset.
searchGravvDocs: search Gravv docs in natural language, with optional section filter and result limit; returns ranked pages and excerpts.getGravvDocPage: fetch full documentation page text by slug or full URL, including handling moved pages.Use these without an API key to learn integration order, prerequisites, recipes, and API reference before implementing Gravv calls.
With
GRAVV_API_KEY, the README says the full server adds ~90 Gravv API tools and 11 goal prompts for customers, KYC, accounts, transfers, cards, wallets, savings, FX, collections, webhooks, and sandbox simulation, with confirmation and live-write safeguards.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@gravv/mcp What Gravv accounts do I have?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@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/mcpGet 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/mcpVS 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/mcpOr 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 |
|
Cursor |
|
Windsurf |
|
Cline | the MCP Servers panel, or |
Zed |
|
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/mcpthen 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 usefulPrompts
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 |
| a bank account or the business's card account; an application the bank is waiting on; deposit details |
|
| create and verify a person or a business; resubmit; read KYC documents |
|
| ACH, wire, RTP, SWIFT, SEPA, Faster Payments, or between own accounts |
|
| a bank account or mobile wallet abroad, in about 60 countries |
|
| USDC or USDT to a wallet; USDT to USDC between own wallets |
|
| quote and place an FX order; settlement instructions; follow or cancel |
|
| verify a cardholder and issue a card; fund, limit, freeze, close |
|
| stablecoin deposits, bank deposits, bank transfers, card checkout, saved cards |
|
| open a savings account, save and withdraw, interest and statements, test it in sandbox |
|
| transactions against the books, one transfer's webhooks, fees, missed events |
|
| pending, paused, under review or failed, and how to answer a pause |
|
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 # everythingToolset | Default | Covers |
| ✓ | create, list, get, update customers |
| ✓ | capabilities, v2 accounts and their applications, and the business's one card account |
| ✓ | transfers, supporting documents, resume, limits, rate-locked quotes, rates, supported countries and currencies |
| ✓ | history, volume, export |
| ✓ | recipients, verification, institutions |
| ✓ | KYC start, server-to-server, document upload and download, status |
| ✓ | issue, balance, status, withdraw, applications, card KYC, feature activation |
| ✓ | blockchain wallet creation and lookup |
| ✓ | a customer's savings, the savings rate and daily statements (sandbox only for now) |
| ✓ | quotes, rates, OTC orders, settlement instructions |
| ✓ | card payment intents, saved cards, and bank transfer collections |
| ✓ | event history, delivery calls, retry |
| ✓ | 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_statusStep 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
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.
Swap
GRAVV_API_KEYfor your live key. The base URL does not change.Reads and non-financial writes work immediately.
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 |
| 5 MB |
| 5 MB |
| 700 KB |
| 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 |
| — | Sandbox or live key; selects the environment. Omit for docs-only mode |
| unset |
|
|
| Client-side request throttle |
|
| Override the API host. Anything but |
| default set | Same as |
|
| Where the documentation tools read the docs. Same as |
|
| Where downloaded files are saved. Same as |
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 toolsgetGravvDocPageA
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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for Modern Treasury — payment orders, transactions, counterparties and ledgers.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for Gainium — manage trading bots, deals, and balances via AI assistants
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP 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 npm1MIT
- FlicenseNot gradedqualityDmaintenanceAn experimental MCP server that lets AI agents interact with guarded payment workflows through typed tools, enabling safe agent-assisted payments with M-Pesa and mock Airtel Money.3-
- AlicenseAqualityDmaintenanceMCP server for the Monei API that gives AI agents access to wallets, transfers, crypto sends, swaps, offramp, and bill payments through natural language.2420 npmMIT
- FlicenseNot gradedqualityBmaintenanceA 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.-