@asterpay/mcp-server

@asterpay/mcp-server

EUR settlement MCP server for AI agent commerce.

The first MCP server that lets AI agents discover and buy from European merchants using the x402 protocol with EUR settlement via SEPA Instant.

Quick Start

Demo Mode (no API key needed)

Try it out immediately with built-in mock data:

{
  "mcpServers": {
    "asterpay-demo": {
      "command": "npx",
      "args": ["@asterpay/mcp-server", "--mock"]
    }
  }
}

Seller Mode

Expose your products to AI agents:

{
  "mcpServers": {
    "my-shop": {
      "command": "npx",
      "args": ["@asterpay/mcp-server", "--mode", "seller"],
      "env": {
        "ASTERPAY_API_KEY": "ap_write_xxxxxxxxxxxx",
        "MERCHANT_SLUG": "your-shop-slug"
      }
    }
  }
}

Buyer Mode

Let your agent discover and purchase from merchants:

{
  "mcpServers": {
    "asterpay-buyer": {
      "command": "npx",
      "args": ["@asterpay/mcp-server", "--mode", "buyer"],
      "env": {
        "ASTERPAY_API_KEY": "ap_buyer_xxxxxxxxxxxx",
        "SPENDING_LIMIT_DAILY_EUR": "50",
        "SPENDING_LIMIT_WEEKLY_EUR": "200"
      }
    }
  }
}

Configuration

Variable	Required	Default	Description
MODE	No	seller	Server mode: seller or buyer
ASTERPAY_API_KEY	Yes*	—	Your API key. *Not needed with --mock
ASTERPAY_API_URL	No	https://api.asterpay.io	API endpoint
MERCHANT_SLUG	No	—	Your merchant identifier (seller mode)
SPENDING_LIMIT_DAILY_EUR	No**	—	Daily spending cap. **Required for buyer mode (non-mock)
SPENDING_LIMIT_WEEKLY_EUR	No**	—	Weekly spending cap. **At least one limit required for buyer mode
DEBUG	No	false	Enable verbose logging to stderr

CLI Flags

asterpay-mcp --mode seller|buyer   # Set mode
asterpay-mcp --mock                # Use demo data, no API key needed
asterpay-mcp --smoke-test          # Run diagnostic check and exit
asterpay-mcp --help                # Show help

Tools

Seller Mode (7 tools)

Tool	Description
list_products	List all products with prices in EUR, descriptions, availability
get_product	Get details for a specific product by ID
check_availability	Check stock status and current price
get_business_info	Operating hours, contact, delivery zones, return policy
place_order	Place an order — returns x402 payment details
get_order_status	Check order status (pending/confirmed/rejected/expired)
get_x402_payment_details	Get x402 facilitator endpoint, USDC amount, network

Buyer Mode (10 tools)

All seller tools plus:

Tool	Description
discover_merchants	Find merchants by category, city, country, or trust score
set_spending_limit	Set soft spending limits within your hard caps
get_spending_summary	View spending today/this week and remaining budget

Resources

Loaded automatically when the server starts:

URI	Content
asterpay://merchant/info	Business name, hours, contact, delivery, returns
asterpay://settlement	Currency (EUR), SEPA Instant, facilitator details
asterpay://trust	Probe KYA trust score (0-100), attestation count
asterpay://agents-txt	Auto-generated agents.txt for discovery

How It Works

AI Agent  →  MCP Server  →  AsterPay API  →  Merchant
   │              │               │              │
   │  list_products               │              │
   │  ──────────────►             │              │
   │              │  GET /products│              │
   │              │  ────────────►│              │
   │              │               │              │
   │  place_order │               │              │
   │  ──────────────►             │              │
   │              │  POST /orders │              │
   │              │  ────────────►│              │
   │              │               │  SEPA EUR    │
   │              │  x402 header  │  ────────────►
   │  ◄──────────────             │              │
   │              │               │              │
   │  Agent pays USDC via x402    │              │
   │  ────────────────────────────►              │
   │              │  AsterPay converts USDC→EUR  │
   │              │               │  ────────────►

x402 Payment

place_order returns an x402 payment header. The actual USDC payment must be executed by your agent's x402 client.

Environments with full x402 support:

• Custom agents with @x402/axios or similar
• Hermes agents
• Any MCP client with x402 integration

Claude Desktop limitation: Claude Desktop does not include an x402 client. Use --mock mode for testing and demos. For production, use a custom agent with x402 support.

Spending Limits

Spending limits are tracked in-memory for the lifetime of the server process:

• ENV hard cap: Set via SPENDING_LIMIT_DAILY_EUR / SPENDING_LIMIT_WEEKLY_EUR. Cannot be exceeded.
• Soft limits: Set at runtime via set_spending_limit. Must be within the hard cap.
• Reset: Limits reset when the server restarts. Each npx invocation starts fresh.

Spending limits are best-effort and not a security boundary. For production enforcement, backend-side limits will be available in a future release.

Security

• Scoped API keys: Use the narrowest scope for your use case (ap_read_*, ap_write_*, ap_buyer_*)
• No secrets in logs: API keys are never logged, even in debug mode
• x402 keys: The MCP server never handles private keys — that's your agent's responsibility
• Prompt injection: ENV hard caps limit damage from prompt injection attacks

Development

git clone https://github.com/asterpay/mcp-server.git
cd mcp-server
npm install
npm run build
npm test

Run locally in mock mode:

MOCK=true npx tsx src/index.ts

License

Apache-2.0 — see LICENSE for details.

Built by AELIRA LTD for the x402 ecosystem.