XP MCP Documentation

Copy-paste recipes. Each request stands alone.

Gated — Bearer required, full tool surface

# Acquire $TOKEN via OAuth 2.1 + PKCE first (see OAuth & Discovery).
# tools/list returns the full surface once authenticated.
curl -X POST https://mcp.xp.tickets/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Authenticated tool. 401 if bearer missing/invalid.
curl -X POST https://mcp.xp.tickets/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_my_tickets","arguments":{}}}'

Streamable HTTP rules: every request must include Accept: application/json, text/event-stream. The server is stateless: no initialize handshake or Mcp-Session-Id is needed, and any request can reach any replica.

Money units

• A money number is US dollars unless its name says otherwise. Send dollars: make_offer_on_listing.amount_per_ticket_usd and create_standing_bid.amount_per_ticket_usd (whole dollars per ticket), get_ticket_listings.min_price_usd/max_price_usd, list_open_listings.min_amount_usd/max_amount_usd (whole-listing totals).
• Read dollars: per_ticket_usd, total_usd, amount_per_ticket_usd, usdc_balance and the unsuffixed dollar fields (price_range, get_in_per_ticket).
• Two exceptions, each beside a total_usd: amount_mu in an x402 quote (micro-USDC a wallet signs verbatim) and amount_minor in a stripe_link or MPP preview (Stripe's cents). Read total_usd; do no arithmetic on them.

Dates and timezones

• For relative dates ("this weekend", "next month"), anchor on _meta.context.today from the most recent tool response instead of guessing. _meta.context.tz_offset is the server's UTC offset; resolve against the user's timezone when known.

Error contract

• Transport-level 401: WWW-Authenticate: Bearer ... resource_metadata="…" — bearer missing/invalid/revoked. Restart OAuth or refresh the token. Distinct flavors: error="invalid_token" (refresh) vs no error attr (start fresh OAuth). On a tools/call the challenge also names the scope to request, e.g. scope="read:account", so a host can step up from an anonymous quote to a signed-in call in one round trip.
• Tool-level error_code: "AUTH_REQUIRED" / "SESSION_EXPIRED": the bearer was accepted by the MCP server but rejected upstream. The server rewrites these into a transport 401 so MCP clients refresh — handle the same as case 1.

Scope vs role

• OAuth scopes define what an issued token is allowed to call.
• Roles are XP user attributes. No role gates MCP access: every signed-in XP account can reach the marketplace surface (offers, listings, swaps).
• A token missing the required scope 403s with a challenge: WWW-Authenticate: Bearer error="insufficient_scope", scope="…" naming the full scope set, plus a JSON-RPC -32003 body with upgrade_url. Re-authorize once with that scope.

Status: enabled

buy_tickets supports four payment rails selected by the rail argument. Use stripe_link, the default, unless the user asks for another:

• rail="stripe_link" — the default (what you get when you omit rail). Pay by card on a Stripe-hosted Checkout page. Two-turn flow: preview returns payment_link and checkout_session_id; after the user pays, call again with confirm=true and checkout_session_id to get order_uuid and stripe_payment_intent.
• rail="privy" — XP-managed Privy wallet, for users who signed in with an XP identity and fund purchases in USDC.
• rail="x402" — agent-held Solana wallet over the x402 protocol with USDC. Two-turn flow: preview returns an x402.accepts[0] PaymentRequirements envelope; settle accepts a base64 payment_proof.
• rail="mpp" — pay by card with a Stripe Shared Payment Token over the Machine Payments Protocol MCP binding. Two-turn flow: preview returns challenges[]; confirming without a credential answers JSON-RPC -32042 (Payment Required) carrying the same challenges, and a rejected credential answers -32043 with a replacement challenge to retry against. Present the credential in params._meta["org.paymentauth/credential"], or in the payment_credential argument when your client cannot send _meta. Echo back the challenge you were given — the charge is keyed on it.

Registered facilitators

The agent picks one per call via the facilitator arg on buy_tickets; the preview envelope returns facilitators_available with these entries. Omit the arg to use the default. No auto-fallback — on failure, retry with a different id. fee_payer = facilitator's sponsoring Solana pubkey, injected into extra.feePayer at preview so the buyer signs with the correct payerKey. Empty (italic buyer-pays-fees) means the buyer keypair pays gas.

Two-turn flow

# Turn 1 — preview (no wallet)
buy_tickets(event_id=<id>, uvid=<uvid>, quantity=<n>,
            confirm=False, rail="x402")
# → returns x402.accepts[0] (PaymentRequirements) + facilitators_available

# You sign accepts[0] locally with your own Solana wallet (see signer below).

# Turn 2 — settle (optionally pick a facilitator id from facilitators_available)
buy_tickets(event_id=<id>, uvid=<uvid>, quantity=<n>,
            confirm=True, rail="x402", payment_proof="<b64>",
            facilitator="payai")            # or another id from facilitators_available

Buyer-side signer (your responsibility)

XP does not ship a signing client. You hold the buyer keypair; build the signed envelope locally per the x402 v2 SVM exact scheme spec. Reference shape in TypeScript:

// Inputs: accepts (= preview.x402.accepts[0]) + your Solana Keypair `buyer`.
// Output: base64 string → pass as `payment_proof` on the settle turn.
import {
  ComputeBudgetProgram, Connection, Keypair, PublicKey,
  TransactionMessage, VersionedTransaction,
} from "@solana/web3.js"
import {
  createTransferCheckedInstruction, getAssociatedTokenAddressSync,
} from "@solana/spl-token"

const conn = new Connection(SOLANA_RPC_URL, "confirmed")
const mint = new PublicKey(accepts.asset)
const payTo = new PublicKey(accepts.payTo)
const amount = BigInt(accepts.amount)        // micro-USDC, 6 decimals
const USDC_DECIMALS = 6

// Facilitator-sponsored fees: read feePayer from envelope. When present,
// buyer signs ONLY the transfer authority; facilitator co-signs gas at
// /settle. When absent (legacy buyer-pays-fees), buyer pays gas too.
const feePayer = new PublicKey(accepts.extra?.feePayer ?? buyer.publicKey)

const buyerAta = getAssociatedTokenAddressSync(mint, buyer.publicKey)
const payToAta = getAssociatedTokenAddressSync(mint, payTo)
// Pre-flight (recommended): assert buyer ATA balance ≥ amount, merchant ATA
// exists, and — only when buyer === feePayer — buyer has SOL for gas.

// Instructions MUST follow the x402 SVM exact order:
//   [ComputeBudget.setComputeUnitLimit, setComputeUnitPrice, TransferChecked].
// No ATA-create. Token-2022 is allowed by the spec but verify facilitator support.
const ix = [
  ComputeBudgetProgram.setComputeUnitLimit({ units: 20_000 }),
  ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }),
  createTransferCheckedInstruction(
    buyerAta, mint, payToAta, buyer.publicKey, amount, USDC_DECIMALS,
  ),
]

const { blockhash } = await conn.getLatestBlockhash("confirmed")
const msg = new TransactionMessage({
  payerKey: feePayer,                         // facilitator's pubkey when sponsored
  recentBlockhash: blockhash,
  instructions: ix,
}).compileToV0Message()

const tx = new VersionedTransaction(msg)
tx.sign([buyer])                              // partial sign — leave feePayer slot empty

const envelope = {
  x402Version: 2,
  scheme: accepts.scheme,
  network: accepts.network,
  payload: { transaction: Buffer.from(tx.serialize()).toString("base64") },
  accepted: accepts,
  extensions: {},
}
const payment_proof = Buffer.from(JSON.stringify(envelope), "utf-8").toString("base64")
// → pass payment_proof to buy_tickets(confirm=True, rail="x402", payment_proof, ...)

Adapt to your language of choice (Python: solana-py / solders; Rust: solana-sdk). The on-the-wire shape is what matters; XP only consumes the base64 payment_proof string.

Facilitator selection

Each preview returns a facilitators_available list with the registered facilitator ids; the agent picks one per call by passing facilitator=<id>. Ids match ^[a-z][a-z0-9_]*$ and double as the human-readable handle. The signed payment_proof is identical across facilitators modulo the extra.feePayer slot. No auto-fallback — on failure (FACILITATOR_UNAVAILABLE / SETTLE_UNKNOWN), re-preview with a different facilitator id and re-sign.

Read more

• Agent-facing prelude (live config): MCP resource text://help/x402-payments
• x402 protocol spec: github.com/coinbase/x402

Anonymous callers can initialize and call any open-world tool, with no sign-in. Sending a valid Bearer on the same endpoint additionally unlocks the authenticated surface, so tools/list / prompts/list / resources/list return different catalogues to anonymous and signed-in callers. Calling an authenticated tool without a Bearer returns 401 + WWW-Authenticate, which is what starts the OAuth flow. A Bearer that is present but invalid or expired always 401s rather than falling back to anonymous, so a stale token prompts a refresh instead of quietly losing tools.

WWW-Authenticate / PRM: https://mcp.xp.tickets/.well-known/oauth-protected-resource/mcp

Tools

Prompts

Documentation resources — text://

Documentation resources — skill://