PhotoMatchFun Developers

Model Context Protocol

MCP ordering guide

Developer setup, Markdown, and client examples

Connect once, then let a capable agent discover the live product contract, prepare print-ready artwork, create a reviewable order intent, hand payment to a trusted x402 wallet, and track delivery.

Connect your client

Use the remote Streamable HTTP endpoint below. Configuration keys vary by client, but the endpoint does not.

https://photomatchfun.com/api/mcp
{
  "mcpServers": {
    "photomatchfun": {
      "type": "streamable-http",
      "url": "https://photomatchfun.com/api/mcp"
    }
  }
}

If your client uses a different label for remote HTTP MCP servers, enter the endpoint using that client's documented format.

Tool inventory

The complete order lifecycle

Tools return structured data as well as readable text, so MCP clients can validate and pass results between steps.

list_products

Discover products that are ready for programmatic ordering and view the current public payment rail.

get_product_configuration

Get the server price, required artwork count, exact pixels, DPI, safe area, bleed instructions, and terms links.

create_asset_uploads

Create the exact set of short-lived binary upload slots required by the selected product.

create_order_intent

Claim uploaded artwork, submit customer-confirmed U.S. delivery details and an optional couponCode, and receive the discounted amount, immutable order digest, and payment URL.

get_order_status

Read payment and fulfillment state with the per-intent status capability; customer details are not returned.

x402 HTTP handoff

Payment signing remains in the buyer's trusted wallet runtime. The order-intent tool returns the exact URL, amount, digest, and expiry needed for that handoff.

Required sequence

Recipient name: first and last required

The integration uses the first word of customer.name as first_name and the remaining words as last_name for delivery and billing. QPMN requires both fields. New intents reject a one-word name. Older unpaid intents with incomplete saved recipient names are blocked before payment or free-order confirmation; create a corrected unpaid intent after customer review. Already-recorded payments and uncertain settlements must continue through the existing recovery flow. Successful intent creation does not prove that the print provider will accept every address detail.

Keep the customer.name field and confirm the actual recipient with the customer. A fictional illustration is Avery Morgan; Avery alone is incomplete. Do not use example details for an order. Confirm email, phone, street and unit, city, two-letter U.S. state, ZIP code, and country US before ordering.

Read the recipient preflight checklist
  1. 1

    Choose a live product

    Call list_products, then get_product_configuration. Do not cache price or artwork dimensions across orders.

  2. 2

    Confirm the recipient and order

    Before create_order_intent or payment, collect the actual recipient's first and last name in customer.name, separated by a space. Do not use a single first name, wallet label, or agent nickname. Ask the customer for missing name details; never invent a surname. If the recipient has only one name, stop and contact support before ordering. Show the current product, total, artwork, terms link, privacy link, and complete U.S. delivery/contact details before recording consent.

  3. 3

    Render complete card fronts

    Create every required canvas at the exact reported dimensions. Extend backgrounds through bleed and keep important content inside the safe area.

  4. 4

    Upload the binary files

    Call create_asset_uploads with the exact required count. PUT one JPEG, PNG, or WebP to each returned URL using only that slot's upload capability.

  5. 5

    Create the order intent

    Pass the asset ID and separate claim capability for each uploaded front, plus a stable opaque idempotency key and the confirmed customer details.

  6. 6

    Review, pay, and track

    Recheck the full recipient name, amount, and digest before authorizing the returned payment URL. Payment success is not fulfillment success. After HTTP 200/202, poll get_order_status with the original intentId and statusToken. Report provider acceptance only when status is fulfilled and fulfillment.providerOrderId is present; this does not mean delivery. If status is fulfillment_failed or fulfillment.needsOperatorReview is true, report that payment succeeded but fulfillment failed, stop automatic ordering, and do not create another order or payment.

Capability hygiene

Treat upload, claim, and status values like temporary passwords for one order.

  • Keep capabilities out of logs, analytics, public tickets, and shared prompts.
  • Never send a wallet private key, seed phrase, card number, or CVC through MCP.
  • Reuse an idempotency key only when every order input is unchanged.
  • On an unknown settlement outcome, retry the same signed payment; do not create a second authorization.

Next: connect the payment handoff

The x402 guide covers wallet-side validation, payment, and safe retries.

Read the x402 guide