list_brands read-only
Search purchasable brands by query, country, and category. Returns brand ids, denominations, and stock. Safe to call repeatedly.
Model Context Protocol
Native tools for any MCP client
Connect over a single Streamable HTTP endpoint and your agent gets six purchasing tools with exactly the same semantics as the REST API. Integer minor units, idempotent buys, a closed error taxonomy, and encrypted single-read codes, all served straight into your model's tool loop.
6tools
Streamable HTTPsingle remote endpoint
MCP-nativetools/list + annotations
Connect
Add the server
Point any MCP client at the remote server over Streamable HTTP and pass your per-agent API key as a bearer token. The server is stateless JSON, so no local process to run and nothing to install.
{
"mcpServers": {
"agentrefills": {
"type": "streamable-http",
"url": "https://agentrefills.com/mcp",
"name": "com.agentrefills/giftcards",
"headers": {
"Authorization": "Bearer ${AGENTREFILLS_API_KEY}"
}
}
}
}
Tools
The six tools
Every tool returns exactly what the server advertises from tools/list, complete with MCP annotations so your client knows what is read-only, what is destructive, and what is safe to retry.
buy_giftcard destructive · idempotent
Start an async purchase. Returns task_id, state, and estimated_seconds at once. Under the cap it settles automatically; re-using client_ref returns the existing task and never charges twice.
get_purchase read-only
Poll a purchase's state. Safe to call repeatedly; when state is completed and code_available is true, call get_code once to release the code.
get_code single release
Release the code, link, or PIN for a completed purchase exactly once and log the access. A second call returns ALREADY_RELEASED. Raw codes are never logged or traced.
check_balance read-only
The calling agent's remaining budget, daily and monthly limits, float cover, and kill-switch state. Read-only and always safe to poll.
request_approval
Re-ping the human approver for a task parked in APPROVAL_REQUIRED. Rate-limited to one per task per hour, so retries stay polite.
Guarantees
Safe by construction
The same policy and payment engine backs both transports, so every safety property holds whether your agent speaks MCP or REST.
- Fail-closed policy. If the policy engine is unreachable or indeterminate, the purchase is denied, never allowed.
- Per-agent caps. Daily and monthly spend limits plus a brand allowlist are enforced per API key before any money moves.
- Human approval over threshold. Purchases at or above your configured threshold park for a human, who is pinged in Slack.
- Encrypted single-read codes. Codes release exactly once through get_code, return ALREADY_RELEASED after, and are never logged or traced.
- Zero duplicate payments. An idempotency key plus a unique payment-per-task constraint make a double charge impossible, even on retry.
- Full audit trail. Every purchase is reconstructable from an OpenTelemetry trace and a double-entry ledger that always sums to zero.
Wire up your agent
Grab a per-agent API key, point your MCP client at the endpoint, and start buying in the sandbox for free. Prefer raw HTTP? The REST contract carries the same six operations.