MCP Server for AI Agent Payments: A Developer Guide

Why MCP for Payments?

MCP is becoming the standard interface between AI agents and external tools. Claude Desktop, Claude Code, Cursor, Windsurf, and a growing number of agent frameworks support it natively. When your agent needs to spend money, MCP provides a clean separation:

• The agent decides what to buy (its reasoning)
• The MCP server decides whether to allow it (governance)
• The payment infrastructure handles how (execution)

This separation means you can add spending governance to any MCP-compatible agent without changing the agent's code. The agent just gets new tools — it learns to check its budget and get approval before spending, the same way it learns to use any other MCP tool.

Architecture Overview

QuetraAI provides two MCP server options:

The remote server runs on Cloudflare Workers at mcp.quetra.dev. It is the recommended option — no local dependencies, automatic updates, and supports multi-agent routing (one API key discovers all your agents and their mandates).

Setup: Remote MCP Server

1. Create Your Agent and Mandate

In the QuetraAI dashboard:

1. Register an agent — give it a descriptive name and description (the LLM uses the description for routing)
2. Create a mandate — define budget, vendor rules, categories, rate limits
3. Activate the mandate — it is now enforced
4. Generate an API key — this scopes to your entire organization

2. Connect to Claude Code

In Claude Code, add the remote MCP server:

# Settings → MCP Servers → Add Remote Server
URL: https://mcp.quetra.dev/<your-api-key>/mcp

Or add it to your project's .mcp.json:

{
  "mcpServers": {
    "quetra": {
      "type": "url",
      "url": "https://mcp.quetra.dev/<your-api-key>/mcp"
    }
  }
}

3. Connect to Claude Desktop

# Settings → Connectors → Add
URL: https://mcp.quetra.dev/<your-api-key>/mcp

The 8 Governance Tools

Once connected, the agent gets access to 8 tools. Here is what each one does and when the agent typically calls it:

quetra_list_agents

Discovers all agents in the organization with their mandate details — budget remaining, per-transaction limit, rule summaries. The LLM uses this to pick which agent identity to use for a task (e.g., a "research" agent vs. a "content" agent).

quetra_evaluate

Pre-flight spending check. The agent passes the amount, vendor, and category. Returns approved/rejected with per-rule pass/fail details. This is the core governance gate — the agent calls it before every purchase.

quetra_check_budget

Returns current budget status: total budget, amount spent, remaining balance, per-transaction limit, and when the next reset occurs. The agent calls this to decide whether to attempt a purchase or conserve budget.

quetra_can_spend

Like quetra_evaluate but returns rejection reasons in plain language. Useful when the agent needs to explain to the user why a purchase was blocked.

quetra_fetch

x402-aware HTTP fetch. Automatically handles the 402 Payment Required flow: the agent calls a paid API, gets a 402 response, the tool evaluates the mandate, and retries with payment headers if approved.

quetra_transactions

Returns recent transaction history — amounts, vendors, categories, approval status. The agent uses this to summarize spending for the user or to make budget-aware decisions.

quetra_acp_checkout

Initiates an ACP (Agent Commerce Protocol) checkout with a merchant. For purchasing digital goods and services via Stripe's agent payment flow.

quetra_stripe_charge

Charges a credit card via Stripe, governed by the agent's mandate. The tool evaluates spending rules first, then creates a Stripe PaymentIntent if approved. Budget is decremented at authorization time. Requires the organization to configure their Stripe secret key in Settings → Payment Integrations.

Multi-Agent Routing

One of the key advantages of the remote MCP server is multi-agent support. Your API key scopes to the organization, not a single agent. When the LLM starts a task, it calls quetra_list_agents to discover available agents and their capabilities:

The LLM picks the right agent for the job and passes that agent's ID to subsequent tool calls. Each agent has its own mandate, budget, and rules — enforced independently.

Setup: Local MCP Server (stdio)

For single-agent setups, air-gapped environments, or when you want to run the server locally:

# Run directly (no install needed)
QUETRA_API_KEY=sk_... QUETRA_AGENT_ID=agent_... npx @quetra/mcp

Or add to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "quetra": {
      "command": "npx",
      "args": ["@quetra/mcp"],
      "env": {
        "QUETRA_API_KEY": "sk_...",
        "QUETRA_AGENT_ID": "agent_..."
      }
    }
  }
}

The local server exposes 7 tools (same as remote minus quetra_list_agents, since it is bound to one agent).

Programmatic Usage

Building your own MCP-compatible agent? You can embed the QuetraAI MCP server directly:

import { createQuetraMCPServer } from '@quetra/mcp';

const server = createQuetraMCPServer({
  apiKey: process.env.QUETRA_API_KEY,
  agentId: process.env.QUETRA_AGENT_ID,
  gatewayUrl: 'https://gateway.quetra.dev',
});

// Connect to your transport
await server.connect(transport);

What the Agent Actually Does

When a governed agent needs to make a purchase, the typical flow looks like this:

1. Agent identifies a need (e.g., "I need to call the OpenAI API for this research task")
2. Agent calls quetra_check_budget to see if it has remaining budget
3. Agent calls quetra_evaluate with the specific amount, vendor, and category
4. If approved, the agent proceeds with the purchase
5. If rejected, the agent explains why to the user and suggests alternatives

The agent learns this workflow naturally from the tool descriptions — no prompt engineering required. MCP tool descriptions tell the LLM when and how to use each tool.

Webhook Integration

For production systems, set up webhooks to get real-time notifications:

• transaction.approved — every approved spend
• transaction.rejected — every rejected spend (with reasons)
• mandate.budget.warning — when spending hits 80% of budget
• mandate.budget.exhausted — when budget is fully consumed

Webhooks are HMAC-SHA256 signed for security and delivered asynchronously. Configure them in the dashboard under Settings → Webhooks.

Next Steps

• Claude Desktop setup guide — step-by-step with screenshots
• OpenClaw integration — native MCP config
• SDK reference — for custom agent frameworks
• What is AI agent spending governance? — the concepts behind the system