XGuard MCP Server

XGuard — Paid API Gateway

Turn any API into a paid API for AI agents.

Register an existing HTTPS API, choose a request price and payout wallet, and share one paid URL. XGuard quotes, verifies and settles authorized payments, executes the request, returns a signed receipt and records platform fees and seller proceeds separately.

• Monetize your API
• Browse paid APIs
• Gateway, fees, payout setup and buyer recovery
• Small Workers, Express and FastAPI integrations
• Revenue-path audit and acceptance limits

External seller routes stay draft without configured payout signing authority. A successful test is not a real customer payment. Production revenue acceptance requires a funded owner-authorized purchase and recorded settlement/delivery.

Scoped agent execution

Give agents capabilities, not reusable credentials.

Store a provider credential on the server, issue a scoped capability, and let an agent execute one authorized operation. XGuard enforces policy, expiration, revocation, budgets and idempotency before injecting the credential. Every completed execution returns a durable result and signed ProofRail evidence.

This branch contains the 5.2.0 release candidate. Its deployment is tracked in the release audit; the production version is reported by identity.

• Operator setup: keep operator/provider keys out of agent context.
• Agent contract: MCP, REST, JavaScript and Python examples.
• Connect MCP: https://api.xguardgate.com/mcp.
• Payment and recovery contract.

import { createExecutionClient } from './sdk/execution.js';
const agent = createExecutionClient({ capability: process.env.XGUARD_CAPABILITY });
const request = {
  operation: 'github.repository.read',
  input: { owner: 'moelayyan90', repo: 'XGuard' },
  idempotencyKey: 'read-xguard-repository-001'
};
await agent.preflight(request);
const output = await agent.execute(request);
// Retain the same key and exact input for recovery; never retry an uncertain write with a new key.
await agent.verify({ proof: output.proof, resultSha256: output.receipt.result_sha256 });

Sixteen explicit adapters cover bounded GitHub, Cloudflare, Slack, Notion, OpenAI, Anthropic, Gemini and Stripe operations. Provider permissions and fees remain operator-specific. Cloudflare deploys and Stripe money movement are not advertised. The free controlled Secretless demo proves authentication, scope denial, once-only execution and signature verification without an external provider or payment.

Public outcome examples

Public page extraction, product offers and feed digests remain secondary examples with their original prices and payment contracts.

Get your first result without an account, key, wallet or installation:

curl https://api.xguardgate.com/v1/execute \
  -H 'content-type: application/json' \
  -d '{"intent":"demo"}'

This runs the real extraction parser on labelled sample HTML. Supply html to process up to 12 KiB of your own document for free. The preview makes no external requests.

Prices are per bounded execution, including fallback. Read the live capability index for current availability, exact prices, limits, schemas and examples. These public outcome adapters do not provide web-wide search, browser rendering or OCR. Supplied merchant data is not independently verified.

One paid call from an agent

Send a supported intent directly, for example {"intent":"Get a technology news digest","limit":10}. The first HTTP request returns 402, the exact price, delivery description, Payment-Required and an input-bound X-XGuard-Quote. A funded x402 v2 client signs and retries the identical body. XGuard verifies and settles before source access.

The repository includes an automatic helper:

import { createXGuardOutcomeClient } from './sdk/outcomes.js';

// payer is your configured x402Client with a caller-owned, funded signer.
const xguard = createXGuardOutcomeClient({ payer, maxAmountAtomic: '2000' });
const output = await xguard.execute({ intent: 'Get a technology news digest' });
console.log(output.result);
// Keep output.recovery private; use it if delivery needs to be retrieved later.
const same = await xguard.getResult(output.recovery);

One logical execute call uses two XGuard HTTP requests for paid work. It refuses payments outside the explicit budget, network or USDC asset. It never creates a new payment to recover an uncertain response. A wallet is required for paid work; installing MCP alone does not provide one. This helper ships in this repository; no new npm release is claimed. See the runnable paid example.

If all sources fail after settlement, the response carries an execution credit bound to the same outcome. Retry with X-XGuard-Credit and the signed quote; no second payment is required. Credit fulfillment is stored and recoverable using the original quote. A credit is not an automatic cash refund. Read-only recovery continues to accept the original quote after its execution expiry; treat that quote as a private bearer token.

JavaScript, Python, MCP and A2A

const response = await fetch('https://api.xguardgate.com/v1/execute', {
  method: 'POST', headers: {'content-type': 'application/json'},
  body: JSON.stringify({intent: 'demo'})
});
console.log(await response.json());

import requests
print(requests.post('https://api.xguardgate.com/v1/execute',
                    json={'intent': 'demo'}, timeout=15).json())

The MCP endpoint lists only xguard_discover, xguard_execute and xguard_get_result. Call xguard_execute with {"intent":"demo"}. Editor configurations are ready to copy.

Funded agents can use the official @x402/mcp client directly. A paid MCP call returns an HTTP 200 JSON-RPC tool result with isError: true and the payment requirements in both structuredContent and content[0].text. The client retries identical arguments with params._meta["x402/payment"]. Preserve the challenge extensions: they carry the payment identifier and signed, input-bound XGuard quote. Successful settlement is returned in result._meta["x402/payment-response"]. The tool output schema covers successful results, price challenges and errors so standard MCP validation succeeds. Installing a plain MCP client still does not supply payment capability or funds.

HTTP execution retains its 402/header flow. New quotes explicitly declare extra.paymentFlow: "upfront"; outstanding older quotes retain their original terms. The existing bounded payer/recovery example remains the easiest complete runnable purchase. No payment is necessary to inspect the price or try supplied HTML.

For A2A, use SendMessage with one user part: {"text":"demo"} or {"data":{"intent":"demo"}}. The same four executable outcomes are the advertised skills.

Agent instructions explain discovery, execution, 402 retry, recovery and errors. OpenAPI starts with POST /v1/execute. Malformed or unsupported intents return repair.suggested_request. English/Arabic intent matching is bounded; arbitrary natural-language jobs are not promised.

Evidence, limits and compatibility

A successful response has ok, intent, capability, result, verification, cost and receipt. Paid receipts and digests establish execution/content integrity, not the truth of a page or a merchant's actual checkout price. Partial source coverage is explicit. Caches require origin permission and caller allowance; product offers always use fresh reads.

HTTPS/443, public-DNS/private-IP checks, manual redirects, bounded decompressed bodies, credential isolation, payment binding, replay protection and durable state remain enforced. The current Cloudflare fetch transport does not pin the connection to the DNS-checked IP; complete DNS-rebinding prevention remains a transport limitation.

Existing credential-backed actions and operator credits remain supported at operator pricing. The old gateway quickstart is archived; durable delegated actions and existing SDK imports remain compatible. Reusable vendor credentials are never required for the public-source outcomes.

Verification and commercial evidence

Run npm ci --prefix apps/relay and node --test apps/relay/src/outcome-http-test.js for real HTTP-socket flows with controlled source/facilitator fixtures and actual quote/proof cryptography. Mock settlement is not an on-chain payment. node scripts/verify-production-identity.mjs verifies public free execution and signed paid challenges without spending funds.

Read the audit, capability selection, distribution work and release verification. The metrics endpoint distinguishes external production settlement, recognized delivery, liabilities and synthetic tests. Event ratios are not user cohorts; actual infrastructure costs and gross margin remain unknown. Working outcomes and successful deployment do not establish customer demand or adoption.

Self-serve purchasing

Try your own HTML, compare the live prices, then follow the paid developer quickstart. The customer script is sdk/examples/outcome-buy.mjs; run it with --help first. It requires explicit --pay, a budget cap and a caller-owned funded Base USDC signer. It saves a private recovery file before submitting a payment authorization. A storage failure stops the purchase. --recover only retrieves an outcome; it never pays again. Private failure details retain any execution credit for the documented credit flow. Recovery/response files contain bearer material and are excluded from this repository. Use --synthetic for operator tests. The older outcome-paid.mjs remains a synthetic verification example, not the customer purchase command.

SDK callers can provide onPaymentPrepared: async recovery => { /* save privately */ }. The SDK awaits this callback before submitting the paid request. Keep a copy of the original request for credit redemption if all sources fail. Public-source outcomes still use x402; operator card credits remain a separate product.