Skip to main content
Glama

Quantum Atlas Stripe X402 Agent Payment Hub

Execute Paid X402 Capability

x402_execute_capability

Execute one priced HTTP 402 capability through the Stripe X402 Hub, debiting exact USD cents from a prepaid spend key and returning the upstream payload, credit receipt, and Ed25519 cryptographic execution attestation. Use this only after confirming capability_id via x402_list_capabilities and verifying pricing via x402_quote_plan; do not use this for price quotes (use x402_quote_plan). Charges prepaid USD credit (pass max_spend_cents as a hard caller ceiling and idempotency_key for safe retries); failed upstream calls (HTTP >= 400) automatically refund credit and restore delegate budgets. Pass approval_id (sba_*) after x402_decide_approval approves an over-cap request. Returns 401/402/403 if the key is missing, underfunded, frozen, or over policy cap.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "capability_id": "<capability_id>"
    },
    "name": "x402_execute_capability"
  }
}

Input Schema

NameRequiredDescriptionDefault
argumentsNoJSON input arguments expected by the target capability (e.g. {"destination": "annapolis"} for reality_harbor_state or {"query": "city dock"} for kb_search).
spend_keyNoStripe-funded master or delegated subagent spend key (format: sbk_<43+ chars>). Optional when the caller supplies the x-atlas-spend-key HTTP header.
approval_idNoSingle-use human spend escalation approval ticket identifier returned by x402_request_approval (format: sba_<16 hex chars>, e.g. sba_aabbccddeeff0011).
capability_idYesPriced capability identifier or route from x402_list_capabilities to execute (e.g. "reality_harbor_state", "kb_search", or "POST /switchboard/chunk").
idempotency_keyNoStripe-standard idempotency key (8-128 chars, e.g. "run-2026-11-22-harbor-01") ensuring retries reuse the exact original reservation without double-charging.
max_spend_centsNoHard client-side spend ceiling in USD cents (e.g. 50 = $0.50). If the live capability price exceeds this value, execution aborts with HTTP 403 before any debit occurs.

Output Schema

NameRequiredDescriptionDefault
okYesTrue when the capability executed and settled cleanly.
resultNoUpstream JSON payload returned by the executed capability.
schemaNoExecution envelope schema (atlas.x402.center_execution.v1).
credit_receiptNoSettled Stripe prepaid credit receipt.
execution_attestationNoDetached Ed25519 JWS cryptographic attestation binding request, response, and settlement.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the generic write/external profile; the description adds the substantive behavior an agent needs: exact USD-cent debit from a prepaid key, the caller ceiling enforced via max_spend_cents, idempotency_key semantics for retries, automatic refund and delegate-budget restoration on HTTP >= 400, and the 401/402/403 failure conditions. The idempotentHint=false annotation is not contradicted, since retry safety is explicitly conditional on supplying idempotency_key.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded: purpose first, then prerequisites, then spend/idempotency/approval behavior, then error codes. Every sentence carries information, though the single-paragraph packing of the approval and error-code clauses makes it slightly harder to scan than a structured breakdown would be.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a paid, externally-calling mutation with six parameters, the description covers prerequisites, spend controls, retry safety, refund behavior, escalation path, and failure modes. With an output schema present, it correctly does not attempt to document payload structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds operational meaning beyond the schema: max_spend_cents is a hard pre-debit ceiling that aborts with 403, idempotency_key prevents double-charging, approval_id is single-use and only valid after an over-cap approval. Only the nested `arguments` object is left to the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Execute one priced HTTP 402 capability through the Stripe X402 Hub') plus what comes back (upstream payload, credit receipt, Ed25519 attestation). It explicitly distinguishes itself from x402_quote_plan, so an agent can separate the two priced-capability tools without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit prerequisite chain: confirm capability_id via x402_list_capabilities, verify pricing via x402_quote_plan, and route over-cap requests to x402_request_approval / x402_decide_approval before passing approval_id. It also states a negative case ('do not use this for price quotes').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources