XP MCP Documentation — Gated (Bearer required)

Copy-paste recipes. Keep $SESSION = the Mcp-Session-Id response header from initialize; reuse it on every follow-up call in the same session.

Gated — Bearer required, full tool surface

# Acquire $TOKEN via OAuth 2.1 + PKCE first (see OAuth & Discovery).
curl -i -X POST http://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":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"demo","version":"1.0"}}}'

# tools/list returns the full surface once authenticated.
curl -X POST http://mcp.xp.tickets/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

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

Streamable HTTP rules: every request must include Accept: application/json, text/event-stream. Capture the Mcp-Session-Id response header from initialize and echo it on every subsequent call in the same session.

Money units

• USD inputs are integer cents (5000 = $50.00). Multiply dollars by 100. Applies to: get_ticket_listings.min_price_cents/max_price_cents, make_offer_on_listing.amount_cents.
• USDC amounts are 6-decimal raw units (4_000_000 = $4.00). Multiply dollars by 1_000_000. Applies to list_open_listings.min_amount/max_amount and response amount_raw fields.
• Display fields (amount_display, *_usd) are human-readable strings — never re-parse.

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).
• 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 (per-tool gating in scope_enforcement.py).
• 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 insufficient_scope.

Status: enabled

buy_tickets supports two payment rails selected by the rail argument:

• rail="privy" — XP-managed Privy wallet. Default for users who signed in with an XP identity.
• 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.

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

Every call requires a valid Bearer; anonymous → 401 + WWW-Authenticate. tools/list / prompts/list / resources/list expose all categories to any authenticated caller. No role gate is applied at tools/call / prompts/get / resources/read.

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

Tools

Prompts

Documentation resources — text://

Documentation resources — skill://