Shatale MCP Server
MCP server for Shatale — AI-native payment infrastructure. Give your AI agents the ability to request purchases within delegated budgets and policy controls, and to check what happened to them.
60-second demo, no API key required
See the whole agent payment lifecycle before you sign up. Guest mode makes no payment and
touches no account of yours. The simulation and policy tools run fully offline; the merchant
and MCC catalog is fetched from the public API without a key. (This line used to say "no real API
call" — measured against a request recorder, guest mode issues three: two catalog reads and an
MCC lookup, all unauthenticated, with no Authorization and no attribution headers.)
1. Run it:
npx shatale-mcp-server
2. Point your IDE at it (Claude Code shown — see Configure your IDE for Desktop/Cursor/Windsurf):
claude mcp add shatale -- npx shatale-mcp-server
3. Ask your assistant:
Use Shatale to simulate an AI agent buying a $25 developer tool subscription with a $100 monthly budget. Show the policy check, approval decision, virtual card step, and final timeline.
You'll see the policy evaluation, the approve / decline / requires-approval decision, the (simulated) virtual card step, and a trace — all in guest mode, with no key.
Tip: call
explain_shatalefirst. It reports the current mode, the tools available to you, and the recommended first prompt.
Run the same flow in sandbox
No code changes required. Add a sandbox key and re-run the same prompt. The guest simulation becomes a real sandbox integration — onboarding, purchase requests, approval, credential issuance, status and audit — against Shatale Sandbox APIs, with no real money.
SHATALE_API_KEY=sk_sandbox_xxx npx shatale-mcp-server
…or just add the key to the env block of your IDE's MCP config (see below) — same prompt, no other changes.
Free sandbox key, no card required → admin.shatale.com/register?ref=mcp
Guest = explore: 7 tools — two offline tools (
simulate_purchase_flow,generate_policy_template), two discovery tools (explain_shatale,list_capabilities) and three catalog reads (search_merchants,get_merchant_details,list_mcc_codes). Sandbox = build: 22 tools — the full lifecycle, including the two checkout reads (get_checkout_customer,get_checkout_cardholder) opened in the sandbox by SHAT-2674, the card reveal (reveal_card) added by SHAT-3023 and the delivery-address read (get_shipping_address) added by SHAT-6291. The exact per-mode list is the tool matrix below, and it is generated from the running server, not written by hand.
register_user_profileandget_onboarding_statuswere removed in 2.0.0 (SHAT-5075), together with theSHATALE_ONBOARDING_ENABLEDswitch that held them back: the API's/v1/onboarding/*routes answer 404onboarding_funnel_disabled, so there is no backend the pair could return for.request_purchasereports when the person must finish onboarding.
get_credential_emailsused to be another one held back. Its suppression named a condition — "#361 merged AND deployed" — and both halves have since been met: the route is registered inapps/api/main.gowith no flag beside it (the commit that added it says "revives #361"), andGET /v1/credentials/{id}/emailson the live API answers 401 from the auth middleware, where a path the router does not serve answers a plain404 page not found. Measured 2026-08-27, with that nonsense path as the control. The flag is removed rather than defaulted on: a switch whose condition is satisfied is one nobody looks at again, and the next reader takes it for a live decision.A live key moves real money, and this document used to say the opposite. Since v0.4 a
sk_live_*key IS accepted — but only together withSHATALE_MODE=live, and the purchase and credential tools are not even registered unlessSHATALE_MONEY_GOhashes to the deploy-timeSHATALE_MONEY_GO_SHA256. A live key WITHOUT the mode flag refuses to start, and the mode flag without a live key refuses too. A local IDE is still not a trust boundary for live payment credentials — that is an argument for not setting those variables, not a claim that the server prevents you.
Configure Your IDE
Omit the
SHATALE_API_KEYenv entirely to run in guest mode (60-second demo). Add ask_sandbox_*key to unlock the full sandbox.
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"shatale": {
"command": "npx",
"args": ["shatale-mcp-server"],
"env": {
"SHATALE_API_KEY": "sk_sandbox_your_key_here"
}
}
}
}
Claude Code
claude mcp add shatale -- npx shatale-mcp-server
Cursor / Windsurf
Add to .cursor/mcp.json or ~/.windsurf/mcp.json:
{
"mcpServers": {
"shatale": {
"command": "npx",
"args": ["shatale-mcp-server"],
"env": {
"SHATALE_API_KEY": "sk_sandbox_your_key_here"
}
}
}
}
Remote transport (streamable HTTP)
The server speaks stdio by default — that is what Claude Desktop, Cursor and every other local MCP client use, and nothing below changes it. A second transport exists for callers that cannot spawn a child process, such as a web application.
The transport is chosen explicitly. It is never inferred from the environment: a server that guesses comes up speaking a protocol nobody on the other end is speaking, which looks like a hang rather than a misconfiguration.
SHATALE_MCP_TRANSPORT=http \
SHATALE_MCP_HTTP_PORT=3000 \
SHATALE_API_KEY=sk_sandbox_... \
npx shatale-mcp-server
Callers present the publisher key as a bearer token:
POST / HTTP/1.1
Authorization: Bearer sk_sandbox_...
Content-Type: application/json
Accept: application/json, text/event-stream
A request with no key is refused with 401 {"error":"missing_key"}; a request whose key is
not accepted is refused with 401 {"error":"key_not_accepted"}. The two are kept apart
deliberately — a caller that has not been wired up yet and a caller wired to the wrong server are
different problems, and a single "unauthorized" for both sends them to the same dead end. No refusal
ever echoes key material.
⚠️ HTTP mode requires a key. Guest mode has no publisher key to authenticate callers against, so
SHATALE_MCP_TRANSPORT=httpwithoutSHATALE_API_KEYrefuses to start rather than listening on a network and admitting everyone.
Both transports advertise the same tools — they are built from one roster rather than two lists that agree today, and a test asks both running transports and compares the sets.
Tools
Tools defined in the code: 22. A tool appears in a column only if the server actually returned it from tools/list in that mode — no column is a plan or an intention.
What each tool does
explain_shatale— Entry point. Reports the current mode (GUEST / DEMO(SANDBOX) / LIVE), the tools available in that mode, the recommended first prompt, and how to move from demo to live. Call this first. No API key required.simulate_purchase_flow— Simulates the Shatale agent payment lifecycle in guest mode: policy check, approval decision (approved / declined / requires_approval), virtual card step and timeline. No real API call or payment is made. Use this before registering for a sandbox key.generate_policy_template— Generates a spending policy template for a use case AND validates it: risk level, warnings, and recommended controls (approval threshold, max transaction, blocked categories). Never returns a silently unsafe policy. No API key required.list_capabilities— Lists all capabilities currently available on this MCP server, based on the configured API key mode.list_mcc_codes— Search or list MCC (Merchant Category Codes) used for spending policy configuration.search_merchants— Search the Shatale merchant catalog. Find merchants by category, capability, keyword, or country. Returns merchants with their MCP capabilities so you can determine which merchants support agent-driven purchases.get_merchant_details— Get detailed information about a specific merchant, including their MCP server configuration, available tools, rate limits, and capabilities. Use this after search_merchants to get integration details.request_purchase— Request a purchase on behalf of a user. Shatale checks it against the spending policies and answers with a STATUS to act on — it does not complete the payment. The answer may say the user must finish onboarding, that a delegation is missing, that policy blocked it, or that it is waiting for approval. When it reaches payment_ready a card has been issued for it and paying at the merchant is the next step, yours to take. If the goods are physical, pass requires_shipping: true. When the person has no shipping address on file the answer is blocked with block_reason shipping_address_required, state action_required, requirements [{type: shipping_address, status: missing}] and a next_action of type open_url: send the person to that URL to add their address, and tell them why. No money moves until an address exists. Never put an address in this request — it is refused; once the purchase is payment_ready, read it with get_shipping_address.get_purchase_status— Get the current status of a purchase request by its ID.await_purchase_approval— Wait for the person to answer a purchase that needs their approval, instead of polling. Returns approved, declined, expired, ended — or still_waiting, which means nobody has answered yet and you may call this again. ended means there will be no answer: the purchase was cancelled, abandoned or failed, its payment hold expired, or it was stopped without the person being asked; its reason field says which, so tell the person what happened, not that they declined. approved with reason not_required means the publisher's policy allowed the purchase and the person was never asked; approved without a reason means the person approved it. Only approved means approved: treat any other outcome, including one not listed here, as not approved. It reads the decision; calling it never changes the purchase, and get_purchase_status keeps working alongside it.
Notes the matrix cannot carry
request_purchaseruns under a sandbox key, and the environment comes from the key. It used to be refused here, and this note used to explain the refusal:/v1/purchaseswas not sandbox-gated on the backend, so a sandbox key would have created real ledger state. SHAT-2373 changed that — the endpoint serves sandbox keys deliberately, the environment is stamped from the key rather than from anything the caller sends, and the money-movers resolve to sandbox implementations. A sandbox key using the same public contract an outsider uses is the point; a separate privileged sandbox route is what the ticket forbids.sandbox_simulate_authorizationis still the narrower tool: it exercises a policy decision without creating a purchase. (SHAT-2611. The previoussandbox_create_test_user,sandbox_decline_request,sandbox_resetandsandbox_approve_requesttools have been removed/renamed in v0.4.0, SHAT-1488.)- The merchant catalog is empty on purpose, and
search_merchantsanswers with an empty list. It is populated as purchases happen; we do not curate it. Measured against the public API with no key:GET /v1/merchants/catalogreturns HTTP 200{"merchants":[],"total":0}for every filter, whileGET /v1/mcc-codeson the same host returns real data — so the emptiness is the catalog, not the connection. Do not build a merchant-discovery step on these two tools today. They are advertised because they work; they return nothing because there is nothing yet. - Raw card numbers are never in a tool result.
request_temporary_credentialsreturns a relay email and a single-use relay password. PAN and CVV are stripped from every tool result (src/redact.ts); card data is delivered out-of-band.
Example Prompts
Try these with your AI assistant. Each prompt names the tool it drives and the mode that advertises it, so a prompt cannot survive here after its tool stops being reachable.
- "Show me what this server can do and what I should ask first"
- "Simulate an AI agent buying a $25 developer tool subscription with a $100 monthly budget"
- "Generate a spending policy for a procurement bot with $5000 monthly limit"
- "Which MCC codes cover airlines and hotels?"
- "Run a sandbox authorization for a $49.99 charge at MCC 5732 and explain the policy decision"
- "Check the status of purchase pur_123"
- "Cancel pending purchase pur_123"
"Search for electronics merchants in Germany" and "What merchants are available in the travel category?" were removed from this list rather than fixed: the tools work, the catalog is empty (see the note above), so those prompts led a reader to an empty list that looks like a broken integration. The gate cannot check this one — it never makes a network call — so it is a claim on a human, re-checked whenever the catalog policy changes.
How It Works
AI Agent → MCP Server → Shatale Sandbox API → issuing partner → virtual card
- Agent requests purchase via
request_purchasewith merchant and amount - Shatale evaluates policy — checks delegation scope, amount limits, MCC rules
- User verifies (if new) — opens personalized onboarding URL, confirms identity
- Virtual card issued — the issuing partner provisions a card locked to the merchant and amount
- Agent receives merchant credentials — a relay email and single-use relay password via
request_temporary_credentials; raw card numbers (PAN/CVV) are never returned in-band, card data is delivered out-of-band - Agent completes purchase — uses card at the merchant
In guest mode none of this hits the network — simulate_purchase_flow walks the same steps deterministically so you can see them before registering for a sandbox key.
Resources
Built-in documentation available as MCP resources:
shatale://guides/quickstart— 5-minute quickstart guideshatale://guides/policies— Policy engine and skills referenceshatale://guides/verticals— Use case examples (shopping, travel, procurement, expense)
Security
- Sandbox keys (
sk_sandbox_*) run the ordinary path. A live key (sk_live_*) is accepted ONLY withSHATALE_MODE=live, and money tools require theSHATALE_MONEY_GOcode as well — three separate things a person has to do on purpose. It is not blocked; it is gated. - Card credentials are encrypted (JWE) and delivered only to authorized agents
- Local stdio transport — no network server exposed
- See SECURITY.md for vulnerability reporting
Release gate
Before a version is published, npm run gate drives the built server over stdio against a
real deployment with a real sandbox key and demands a policy decision back — not merely the
absence of an error, because the backend answers HTTP 400 for "agent not found" exactly as it
answers it for a rejected body, and the MCP discards upstream bodies. This is the check that
would have stopped 0.2.1 and 0.5.0, both of which shipped green.
See docs/release-gate.md.
Privacy & telemetry
This server has no telemetry: no analytics endpoint, no beacons, no install ID, no fingerprinting.
-
Guest mode (no API key) sends no attribution headers and no telemetry. The simulation tools (
simulate_purchase_flow,generate_policy_template) run fully offline and make no network calls. Guest activity is intentionally not measured remotely. -
Sandbox mode (
sk_sandbox_*) already authenticates to the Shatale Sandbox API. Those requests carry three static attribution headers so we can understand aggregate adoption of the official client:User-Agent: shatale-mcp-server/<version>X-Shatale-Client: shatale-mcp-serverX-Shatale-Client-Version: <version>
These add no new transport, endpoint, or payload — they only label calls you are already making. Analytics are derived server-side from your authenticated activity.
-
Never collected: API key values, prompts, policy contents, merchant/customer/card data, PAN, and no machine identifiers (OS, hostname, username, file path, or persistent install ID).
Links
License
MIT
