PhotoMatchFun logo

Model Context Protocol

MCP ordering guide

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 receive an 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

  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 with the customer

    Show the current product, total, terms link, privacy link, and U.S. delivery 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

    Verify the returned amount and digest, pay the returned URL with an x402 v2 client, then call get_order_status until fulfilled or operator review is requested.

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