MCP server Agent Commerce Gateway

What it is, in ten seconds

You already have an HTTP API. Agent Commerce Gateway lets AI agents discover, call and pay for it without adding those protocols to your backend.

Run the gateway in your infrastructure and describe each endpoint in YAML, or generate draft resource definitions from OpenAPI. Resources can be exposed over HTTP, MCP or experimental A2A; dedicated resources can implement experimental ACP checkout operations. Paid resources use x402 or experimental MPP and can also require an AP2 mandate proving that the buyer approved the purchase. Funds go directly to the merchant wallet, and the gateway needs neither the buyer's nor the merchant's private key.

Your existing API → Agent Commerce Gateway → AI Agent
    MCP · A2A · ACP · x402 · MPP · AP2 · receipts · doctor

Demo

[agent] Agent Commerce Gateway: deterministic buyer demo
[buyer] balance before  100 MockUSDC
[agent] merchant balance before 0 MockUSDC
[gateway] connected to http://localhost:8080/mcp
[agent] discovered 2 tool(s): weather_basic, market_report
[agent] paid tool: "market_report", free tool: "weather_basic"
[gateway] 402 payment required: 0.01 USDC to 0x7099…79C8
[buyer] challenge checked before signing: pays 10000 units of 0x5fbd…0aa3 to 0x7099…79C8
[buyer] signed x402 payment proof (LOCAL DEVELOPMENT ONLY - DO NOT FUND)
[gateway] delivered "market_report"
[receipt] id=receipt_484b…1eba requestId=mcp_4292…c930 status=settled settlementTx=0x0b19…1c7f
[buyer] balance after   99.99 MockUSDC  (Δ -0.01)
[agent] merchant balance after  0.01 MockUSDC  (Δ 0.01)
[agent] on-chain balance changes match the expected payment amount
[gateway] delivered free tool "weather_basic": {"city":"Paris","temperatureC":-4,…}
[agent] demo complete: free and paid delivery both verified

This excerpt of npm run demo:agent omits the address lines and shortens long values. Balances, IDs and hashes differ from run to run.

The dashboard at http://localhost:5173 polls the gateway's events route and shows the same request within a few seconds.

Install

npx @devlab.group/agent-commerce --help # no install needed
npm install -g @devlab.group/agent-commerce # or install the `agent-commerce` binary
agent-commerce doctor

Requires Node >= 22. The package includes the agent-commerce CLI (init, validate, start, doctor, reconcile, resolve, demo, import openapi, version) and a library for embedding the gateway. The default install excludes optional protocol, payment and authorization peers. The OpenAPI parser is a regular dependency because import is part of the CLI.

agent-commerce start --config config.yaml --env-file .env

start runs the configured gateway in the foreground until SIGTERM or SIGINT. Install the optional peers for the features you enable, listed below. Missing startup imports stop the gateway with an error naming the package; missing Solana, NEAR or CDP peers fail provider health checks or payment requests. start, validate, doctor, reconcile and resolve accept --env-file <path> to load environment variables before reading the config. Variables already set in the environment take precedence. To embed the gateway in your own process, use the library:

import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';

const config = await loadConfig({ path: 'config.yaml' });
const store = receipts({ path: './receipts.sqlite' });
// Initialize before use so an incompatible SQLite schema fails at startup
await store.init();

const gateway = await createGateway({
  config,
  store,
  paymentProviders: [],
  protocolAdapters: [],
});
const { url } = await gateway.listen();

Optional peers

Components with extra dependencies use separate subpaths, so a gateway serving free HTTP resources does not install MCP, EVM, JOSE or SD-JWT packages.

You want	Install	Import
gateway, config, receipts, A2A/ACP, CLI	@devlab.group/agent-commerce	from '@devlab.group/agent-commerce'
expose resources as MCP tools	+ @modelcontextprotocol/server	from '@devlab.group/agent-commerce/mcp'
accept x402 payments	+ @x402/core @x402/evm viem	from '@devlab.group/agent-commerce/x402'
accept x402 on Solana	x402 peers + @x402/svm @solana/kit	(no import - loaded for a Solana offer)
accept x402 on NEAR	x402 peers + @x402/near	(no import - loaded for a NEAR offer)
accept MPP payments	+ mppx viem @x402/core @x402/evm	from '@devlab.group/agent-commerce/mpp'
verify AP2 mandates, sign checkout JWTs	+ jose @sd-jwt/core canonicalize	from '@devlab.group/agent-commerce/ap2'

The x402 entry needs @x402/core, @x402/evm and viem even when every offer is on Solana or NEAR. MPP settles through an x402 facilitator, so its entry also needs the x402 peers.

npm install @devlab.group/agent-commerce @modelcontextprotocol/server @x402/core @x402/evm viem

import { mcp } from '@devlab.group/agent-commerce/mcp';
import { x402 } from '@devlab.group/agent-commerce/x402';
import { ap2 } from '@devlab.group/agent-commerce/ap2';

AP2 peers remain optional because a deployment without mandate-gated resources does not need JOSE or SD-JWT support.

Peers are pinned exactly: x402's schemas and EIP-712 domains cross this boundary, so a version skew is a correctness problem rather than a convenience one. Importing a subpath without its peer fails at load time and names the missing package.

Testing a custom store

createGateway accepts a custom ReceiptStore. The experimental ./testing entry exports conformance cases to test it. The cases use node:assert/strict and import no test runner or optional peers, so you can wrap them with your runner:

import { receiptStoreConformanceCases } from '@devlab.group/agent-commerce/testing';
import { it } from 'vitest';

const cases = await receiptStoreConformanceCases(({ clock }) => ({
  store: createMyStore({ clock }),
}));
for (const c of cases) it.skipIf(c.skip !== undefined)(c.name, () => c.run());

Have the factory return a new, empty store for each case. The suite calls init() and close(). Pass the supplied clock to the store so expiry cases can advance time without waiting.

Each optional method group, such as authorization holds, must be implemented in full or omitted; one case checks this. Cases that need missing methods are marked to skip. Durability cases also skip unless the factory returns reopen(), which must close the current store and open another over the same data. Concurrency cases submit competing reservations, resolutions, idempotency claims and pending-task takes, then check that exactly one caller wins.

Integrate with an AI coding agent

The repository includes an experimental Agent Skills skill, agent-commerce, for adding the gateway to an existing API. It covers Base Sepolia configuration, startup and checks through an unpaid 402 challenge. Its instructions keep secrets out of chat and leave payment signing to the user. The skill has automated CLI and config checks.

# Claude Code
/plugin marketplace add devlab-group/agent-commerce
/plugin install agent-commerce-gateway@agent-commerce

# Codex, Cursor and other agents (a third-party installer)
DISABLE_TELEMETRY=1 npx skills add devlab-group/agent-commerce --skill agent-commerce

Quickstart

Requirements: Node >= 22, npm 10, Docker. Nothing else - no API keys, no real money, no manual blockchain setup.

git clone <repo> && cd agent-commerce
npm install
docker compose up

Then, in a second terminal:

npm run agent-commerce -- doctor --config config-demo.yaml # verify the whole stack
npm run demo:agent # watch an agent buy something

Linux: if your UID/GID is not 1000, export DOCKER_UID=$(id -u) DOCKER_GID=$(id -g) before docker compose up. This keeps the generated deployment manifest host-writable. Docker Desktop does not need this.

The disposable local stack includes Anvil, MockUSDC, a demo merchant API, the gateway and a dashboard.

To stop and wipe state: docker compose down -v.

agent-commerce demo

From a repository clone, one command starts the stack and runs the buyer agent:

npm run agent-commerce -- demo

It starts the stack with docker compose up --build --detach --wait, which returns once every service with a health check is healthy, then runs npm run demo:agent. A failing step stops the run with exit code 1, after printing the end of its error output and the command to rerun it by hand. demo does not run doctor. The Linux note above applies, and the stack keeps running in the background until docker compose down -v.

How it works

┌──────────────────────────────────────────────────────────────────────────────┐
│                                   AI Agent                                   │
└───────────────────────────────────────┬──────────────────────────────────────┘
                                        │  MCP · A2A · ACP · HTTP
                                        │  payment proof
                                        │  Agent-Authorization
┌───────────────────────────────────────▼──────────────────────────────────────┐
│                        Agent Commerce Gateway (yours)                        │
│                                                                              │
│                   protocol adapters  →  ExecutionPipeline                    │
│                                                 │                            │
│             ┌────────────────────┬──────────────┴──┬────────────────┐        │
│             ▼                    ▼                 ▼                ▼        │
│   AuthorizationProvider   PaymentProvider   BackendExecutor   ReceiptStore   │
│           (ap2)             (x402, mpp)     (bounded HTTP)      (SQLite)     │
└───────────────────────────────────────┬──────────────────────────────────────┘
                                        │
                             ┌──────────▼─────────┐
                             │  Your backend API  │
                             └────────────────────┘

Every protocol adapter uses one execution pipeline, so payment enforcement does not depend on the adapter. See Architecture.

Configure a resource

resources:
  market_report:
    name: Premium Market Report
    backend:
      type: http
      method: GET
      url: ${MERCHANT_API_BASE_URL}/api/report
      timeoutMs: 10000
    pricing:
      type: fixed
      amount: "0.01"
      currency: USDC
    expose: [http, mcp]
    payments: [x402]

The gateway calls your existing backend, which needs no SDK or changes.

npm run agent-commerce -- init # generate a config interactively
npm run agent-commerce -- validate # fails loudly, exits non-zero

Already have an OpenAPI description? Generate the resources from it (experimental):

agent-commerce import openapi ./openapi.yaml

It writes a reviewable resources: fragment with path, query and JSON body bindings and supported schemas. The source document never decides price or exposure: pricing appears only with --free and expose only with --expose, and credentials are never imported. See OpenAPI import for the supported subset.

See docs/configuration.md.

Protocol support

Protocol	Status	Pinned revision
HTTP	Supported	native routes
MCP	Supported	2026-07-28 and 2025-11-25, @modelcontextprotocol/server@2.3.0
x402	Supported	x402 v2 (@x402/core, @x402/evm, @x402/svm, @x402/near), scheme exact, EVM and Solana; NEAR partial
MPP	Experimental	mppx@0.13.1, charge + evm + EIP-3009, USDC on Base Sepolia and Base
A2A	Experimental	A2A v1.0.1, binding JSONRPC, method SendMessage, x402 extension
ACP	Experimental	ACP 2026-04-17, REST checkout + discovery
AP2	Experimental	AP2 v0.2.0, Direct Checkout Mandate verification
ERC-8409	Experimental	draft SergeevDmitry/ERCs@0ee33230: signed quotes on x402 EVM offers
UCP	Planned	no implementation

AP2 is an authorization method, not a transport. It verifies a mandate before a paid resource settles; the gateway does not issue the mandate or its Checkout Receipt.

The experimental entries above ship off by default with documented subsets: A2A, ACP, AP2, MPP and ERC-8409 quotes. Supported MCP and x402 are also scoped. ACP exposes only its five checkout operations; merchant payment_data is never converted into a gateway payment proof.

GET /.well-known/agent-commerce reports supportedSpec, capabilities and unsupported for registered adapters and providers. agent-commerce doctor prints the unsupported lists for A2A, ACP and AP2 when they are enabled.

Versioning

Minor releases may break experimental configurations, integrations or types: MPP, A2A, ACP, AP2, ERC-8409 quotes, agent-commerce import openapi, PaymentProvider.reconcile, the ReceiptStore methods and types added in 2.6.0, the idempotency resource settings with the store and provider methods added in 2.7.0, and the ./testing entry.

The journal's Transaction type, ReceiptStore journal methods and /api/transactions response shape are supported. The transactionId fields, receiptCommitted and flags accepted by reconcile and resolve are also supported.

Experimental runtime adapters and providers identify themselves with status: experimental in GET /.well-known/agent-commerce. Pin experimental integrations to an exact version and test upgrades before deployment. Since 2.1, some supported x402 behavior and types differ from 2.0; see Upgrading from 2.0 to 2.x.

Payment model

• Non-custodial. Buyer payments go directly to the merchant address in payTo (recipient for MPP). The gateway does not require buyer or merchant private keys. Local facilitator mode uses a separate key to pay gas. Experimental ERC-8409 quotes use a dedicated, unfunded signing key.
• Fail closed. Missing, malformed, expired, replayed, wrong-amount, wrong-recipient, wrong-network and wrong-asset payments are rejected.
• Replay-safe twice over. The EIP-3009 or Permit2 nonce stops a double spend on-chain; the gateway additionally reserves a replayKey derived from the authorization before it settles anything.
• Retry after a lost response (experimental, disabled by default). With idempotency.redelivery, buyers can retrieve a stored response without another charge using the same wallet, input and x402 payment-identifier id or MPP Idempotency-Key. Matching exact resends skip verification until retention ends, an exception to fail closed. Responses are stored unencrypted in the receipt database. idempotency.merchantKey sends a derived Idempotency-Key to the merchant for paid operations. See Retry after a lost response.
• On-chain settlement in CI. The end-to-end test asserts the buyer's balance falls and the merchant's rises by exactly the price, with a real transaction hash in the receipt. A log line saying "payment successful" would not count.
• One selected rail per resource. A resource can name several rails, such as payments: [x402, mpp]; the first enabled one serves it, and nothing selects or falls back between rails per request.
• Authorization is separate from payment. A resource can also require an AP2 mandate, verified before settlement and spendable exactly once. It never moves money and never unlocks a resource on its own - the payment still has to be real.

Public networks

Public networks use the same execution pipeline with a remote facilitator. Choose the network in config; Base mainnet also requires allowMainnet: true.

It has actually settled

These transactions each moved 0.01 USDC from a buyer to a merchant through a remote facilitator:

Rail	Network	Method	Transaction
x402	Base Sepolia	EIP-3009	0xea41b234c4…
x402	Base Sepolia	Permit2	0xa66f56cf39…
x402	Base	EIP-3009	0x57ec81c2a3…
x402	Base	Permit2	0x79d3da1145…
x402	Solana Devnet	SPL transfer	5289xbeyHJ…
x402	Solana	SPL transfer	E7gAuG8pMA…
x402	NEAR Testnet	NEP-141 transfer	5tdtGLv4TB…
x402	NEAR	NEP-141 transfer	7hU3imHepV…
MPP	Base Sepolia	EIP-3009	0x5d9fcd111b…
MPP	Base	EIP-3009	0xf4255bd7ec…

Facilitators broadcast these payments and paid their ETH, SOL or NEAR fees. Permit2 requires an initial, gas-paying token approval from the buyer. The NEAR runs used the suite's SDK facilitator and relayer; support remains partial pending hosted-facilitator settlement. Buyer and merchant keys stayed outside the gateway. The smoke suites verified settlement on-chain.

Reproduce with npm run test:testnet, which spends test USDC, or npm run test:mainnet, which spends real USDC. Both run only by hand; see Base mainnet and smoke tests. The suites also cover NEAR testnet and mainnet (settled) and Arbitrum Sepolia (not yet run).

The facilitator model

A facilitator verifies the buyer's authorization and broadcasts the transfer. It is the only component that needs gas.

facilitator.mode	Who signs	Where it is allowed
local	this process, with a key you configure	a local Anvil chain; refused on mainnet, fails readiness elsewhere
remote	an HTTP facilitator you point at	anywhere

With remote, the gateway holds no facilitator signing key. The buyer signs an EIP-3009 authorization without ETH, and the facilitator pays gas. Because the authorization fixes the recipient, amount and chain, the facilitator cannot redirect the transfer. It can see authorizations and refuse service.

Remote facilitator auth supports none, bearer and cdp. CDP auth signs a fresh JWT per request with the CDP API key. No auth mode needs an extra peer package. Config load rejects other types.

Base Sepolia

payments:
  x402:
    enabled: true
    network: eip155:84532
    rpcUrl: https://base-sepolia-rpc.publicnode.com # health checks only
    asset: "0x036CbD53842c5426634e7929541eC2318f3dCF7e" # Circle USDC
    assetName: USDC
    assetVersion: "2"
    assetDecimals: 6
    payTo: ${MERCHANT_WALLET}
    maxTimeoutSeconds: 300
    facilitator:
      mode: remote
      url: https://x402.org/facilitator
      auth: { type: none }

Full config in examples/base-sepolia/. Test USDC from faucet.circle.com; the buyer needs no ETH. npm run test:testnet drives the whole flow and reads the result back off the chain.

The local dev chain is eip155:31337, Anvil's default chain id, so the network says whether a deployment is local, testnet or mainnet. doctor, health() and /.well-known report it.