veyra-mcp
This server lets an AI agent make policy-constrained USDC payments on Base from a wallet the owner controls, and check budgets, capabilities, sources and payment status.
Check capabilities (
get_capabilities): see available rails, networks, assets, limits and the recipient allowlist currently in force. Read-only.Check budget (
get_budget): view remaining daily allowance, per-payment limits and policy summary; don't retry if blocked.List payment sources (
list_payment_sources): see masked funding sources and whether each can settle unattended (never exposes secrets).Create payments (
create_payment): send USDC on Base to a recipient with amount, reason and an idempotency key; server-side policy decides execution, human approval (awaiting_approvalwith an approval link) or refusal.Verify payments (
get_payment): get canonical state, settling rail,tx_refandexplorer_url— the proof a payment completed; always check before assuming failure.List payments (
list_payments): review this endpoint's recent payments, optionally limited.Cancel payments (
cancel_payment): cancel a payment while it is still cancellable.Stay safe by design: simulated settlements (
confirmed_simulated) move no real money; policy refusals come back asfailedresults with apolicy_reason, not exceptions; reuse idempotency keys rather than creating duplicate payments.
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., "@veyra-mcp Pay 10 USDC to vendor@acme.com for the API invoice"
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.
The problem
Agents increasingly need to pay for things: an API call, a dataset, a bounty, another agent. Today the choices are bad:
Hand the agent a private key. One prompt injection away from an empty wallet.
Hand it a card. No per-call limits, no allowlist, and your bank will not tell you which tool call spent the money.
Approve every payment by hand. Then it is not really an agent.
Veyra is the layer in between. You connect a wallet you already own, set what an agent may spend, and hand the agent one MCP endpoint. The agent gets tools like create_payment. It never sees a key, and it cannot exceed the limits you set because the limits are enforced by Veyra's server, not by the model following instructions.
agent ──MCP──▶ veyra.money ──policy──▶ your wallet ──USDC on Base──▶ recipient
│
├─ under auto-max → executes from your capped on-chain allowance
├─ in the ask band → you approve in your own wallet (one link)
└─ over the limits → blocked, agent is told whyRelated MCP server: pay-mcp
60-second setup
Sign up at veyra.money, connect a wallet (or start with the simulated source, which moves no money).
Create an MCP endpoint with limits. Copy the credential (it starts with
veyra_).Add it to your host:
claude mcp add --transport http veyra https://veyra.money/api/mcp \
--header "Authorization: Bearer veyra_..."{
"mcpServers": {
"veyra": {
"url": "https://veyra.money/api/mcp",
"headers": { "Authorization": "Bearer veyra_..." }
}
}
}export VEYRA_TOKEN=veyra_...
codex mcp add veyra --url https://veyra.money/api/mcp --bearer-token-env-var VEYRA_TOKENgemini extensions install https://github.com/zapxlabs/veyra-mcpThe extension runs the veyra-mcp stdio bridge and asks for your veyra_... token as a setting. You can also set VEYRA_TOKEN in your shell before starting Gemini CLI.
{
"mcpServers": {
"veyra": {
"command": "npx",
"args": ["-y", "veyra-mcp"],
"env": { "VEYRA_TOKEN": "veyra_..." }
}
}
}The veyra-mcp binary is a stdio bridge: it holds the credential locally and relays every call to the hosted endpoint. No policy lives in the bridge.
curl -s https://veyra.money/api/mcp \
-H "Authorization: Bearer veyra_..." \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_budget","arguments":{}}}'Then ask the agent to do something that costs money and watch the policy decide.
Tools the agent gets
Tool | What it does |
| Rails, networks, assets, limits and the recipient allowlist in force right now |
| Daily limit, spent today, per-payment limit, auto and ask bands |
| Masked sources and whether each can settle without a human |
| Create a payment intent. Policy is applied server-side and the result says what happened |
| Canonical state for one payment, including which rail settled it |
| Recent payments for this endpoint |
| Cancel while still cancellable |
Every payment reports one of these statuses:
Status | Meaning |
| Value moved on-chain |
| Settled on the simulated rail. No money moved. The agent is told this explicitly |
| In the ask band. |
| Transaction sent, waiting for the chain receipt |
| Created, not yet evaluated or executed |
| Terminal. Blocked-by-policy payments are |
Use it from code
npm install veyra-mcpimport {
VeyraClient,
VeyraToolError,
idempotencyKey,
movedRealMoney,
paymentOutcome,
} from "veyra-mcp";
const veyra = new VeyraClient({ token: process.env.VEYRA_TOKEN! });
const budget = await veyra.getBudget();
console.log(`spent ${budget.spent_today} of ${budget.daily_limit} USDC today`);
const payment = await veyra.createPayment({
amount: "1.25",
recipient: "0x1234…abcd", // USDC on Base
reason: "Weather API, 500 calls",
idempotency_key: idempotencyKey("weather"),
});
switch (paymentOutcome(payment)) {
case "settled":
// The only case where value actually moved.
console.log("paid —", (await veyra.getPayment(payment.payment_id)).tx_ref);
break;
case "simulated":
console.log("settled on the simulated rail; no money moved");
break;
case "awaiting_approval": {
console.log("owner must approve:", payment.next_action?.url);
const settled = await veyra.waitForPayment(payment.payment_id);
console.log(movedRealMoney(settled) ? "paid" : paymentOutcome(settled));
break;
}
case "blocked":
console.log("policy refused it:", payment.policy_reason);
break;
}Policy refusals are not exceptions
This is the one thing worth reading twice. A payment the policy declines comes
back as an ordinary result with status: "failed" — the call did what it was
asked and the answer was no. Only a malformed argument, a bad credential or an
unknown id throws.
So try/catch is the wrong tool for detecting refusals: it misses every
blocked payment and reads it as a success. Use paymentOutcome, and use
movedRealMoney before telling anyone value moved — it returns false for a
simulated settlement even though the status begins with "confirmed".
Reserve catch for what genuinely failed:
try {
await veyra.createPayment({ /* … */ });
} catch (e) {
if (e instanceof VeyraToolError) {
console.log(e.code, e.message); // VALIDATION_ERROR, UNKNOWN_CREDENTIAL, NOT_FOUND
} else throw e;
}Never retry because you are unsure
If you cannot tell whether a payment worked, read it — do not create
another. getPayment returns tx_ref once a real payment has settled, which
is both your confirmation and what you show the recipient as proof. Reusing the
same idempotency_key returns the original payment; a new key spends again.
Veyra also sets possible_duplicate_of when an identical payment to the same
recipient is already live.
VEYRA_TOOLS exports the tool definitions as JSON Schema, so you can register them with the Vercel AI SDK, LangChain, or plain function calling without a network round-trip. See veyra-examples for complete agents built with the Claude Agent SDK and the Vercel AI SDK.
What you are trusting
Worth being blunt, because this is money.
Veyra never holds your funds. Payments go from your wallet to the recipient. There is no Veyra balance in the middle.
Above your auto-approve limit nothing is delegated. You sign each transfer in your own wallet from the approval link. Veyra verifies the on-chain receipt matches the request.
Within your auto-approve limit you grant a capped ERC-20 allowance to a relayer Veyra operates, the same
approveprimitive every DeFi app uses. The token contract enforces the cap. Veyra's policy engine decides the destination within that cap, so size the allowance like a float you could lose, and use the recipient allowlist when you know who the agent should be paying. Revoke it any time.The simulated rail exists so you can wire everything up before touching real funds. It is labelled everywhere: status
confirmed_simulated,simulated: true.Every decision is in the audit log, including limit changes and credential rotations.
Full details: How a payment actually moves and What you are trusting, exactly.
FAQ
Which networks and assets? USDC on Base. One stablecoin keeps the dollar limits exact without a price feed, and Base is where the agent-payment ecosystem already settles. More rails are on the roadmap; open an issue if you need one.
Does this work with x402 or pay-per-call APIs? Yes, in the sense that matters: the agent asks Veyra to pay the seller's address and gets a receipt. Veyra is the spending policy, not the protocol on the other end.
Can I self-host? Not today. This repo is the client and bridge; the policy engine is the hosted service at veyra.money. The wallet-approval path is fully non-custodial regardless.
What does it cost? There is a free plan. See pricing.
Where do I report a bad policy decision? From the dashboard, so support can see your audit log. This repo's issues are for the client and bridge.
Development
npm install
npm test # builds, then runs the suite against a local mock of the endpointSee CONTRIBUTING.md and SECURITY.md.
Links
Product: veyra.money · Docs · Pricing
Examples: zapxlabs/veyra-examples
MCP Registry name:
io.github.zapxlabs/veyra
MIT © Veyra
Available Tools
7 toolscancel_paymentCInspect
Cancel a payment only while still cancellable.
Inputs: payment_id (required).
create_paymentAInspect
Create a payment intent. Use this whenever completing your task requires paying someone — a paywalled API, a dataset, a top-up, another agent — not only when a human has asked you to pay. Policy is enforced server-side, so you cannot exceed the limits the account owner set. Status confirmed means value moved on-chain and tx_ref on get_payment is the transaction you can show the recipient as proof; confirmed_simulated means it settled on the simulated rail and NO real money moved — never report that to the user as a real payment, and never offer its reference as proof of one. If status is awaiting_approval, give the user next_action.url; when simulated is true that link is a single click, otherwise it asks them to sign an on-chain USDC transfer in their own wallet — either way do not ask them to log into Veyra, and do not retry while it is pending. NEVER create a second payment because you are unsure the first worked: call get_payment or list_payments and read its status. Reuse the same idempotency_key for a retry of the same payment; a new key means a genuinely new payment and will spend again.
Inputs: asset (required), amount (required), reason (required), network (required), +2 more.
get_budgetAInspect
Return remaining daily allowance and policy summary. Read-only. If blocked by limits, ask the human user — do not retry.
Inputs: no named parameters.
get_capabilitiesAInspect
Return the rails, networks, assets and policy constraints actually available to this endpoint right now, including any recipient allowlist. Read-only.
Inputs: no named parameters.
get_paymentAInspect
Get canonical state for one payment request, including which rail settled it and, once confirmed on a real rail, tx_ref — the on-chain transaction — plus explorer_url. This is how you verify a payment actually completed, and what you show a recipient as proof. Always call this before concluding a payment failed.
Inputs: payment_id (required).
list_paymentsCInspect
List this agent's recent payments.
Inputs: limit.
list_payment_sourcesAInspect
List masked payment sources available to this agent, including whether each can settle unattended. Never request secrets.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct action or resource: capabilities, budget, payment sources, and individual payments are clearly separated. The only mild overlap is between get_capabilities and get_budget, since both surface policy/limit information, but their focuses are distinct enough to avoid real confusion.
All tool names follow a consistent verb_noun snake_case pattern: get_, list_, create_, cancel_. Reading operations consistently use get_ for single resources and list_ for collections, making the naming predictable and easy to navigate.
Seven tools is well-scoped for a payment-focused server. Each tool covers a necessary part of the payment lifecycle or policy context without unnecessary duplication or bloat.
The surface covers the full agent-relevant payment workflow: discover capabilities, check budget, list payment sources, create a payment, retrieve one payment, list past payments, and cancel when possible. There are no obvious dead ends or missing core operations for the stated purpose.
Maintenance
Related MCP Connectors
Non-custodial stablecoin bill-pay rails on Celo & Base for AI agents, settled on-chain via MCP.
PHANTOM ID MCP payment server: agent-to-agent USDC payments on Base.
Payment infrastructure for AI agents: spending rules, approval flows, single-use virtual cards.
Pay-per-use MCP tools for AI agents. USDC on Base via x402. No API keys.
Related MCP Servers
AlicenseAqualityDmaintenanceProvides a non-custodial USDC wallet on Base for AI agents, with human-in-the-loop approval for every payment.45 npmMIT- AlicenseAqualityDmaintenanceAn MCP server for USDC payments on Base, enabling AI agents to check balances, send payments, generate payment requests, and view transaction history.42MIT
- AlicenseAqualityBmaintenancePayment infrastructure MCP server enabling AI agents to make gasless USDC payments on Base and JIT single-use virtual card checkouts, with zero-trust card handling, merchant checkout hints, and signed receipts.13136 npm1MIT
- AlicenseAqualityCmaintenanceEnables AI agents to quote, authorize, submit, and verify agent-to-agent USDC payments on Base through standard MCP tools over stdio.4316 npmBusiness Source 1.1