Connect your agent to PhotoMatchFun

• list_products — Read available products, current USD totals, artwork requirements, and the active x402 payment configuration.
• get_product_configuration — Read one product’s exact canvas dimensions, safe area, bleed, required front count, price breakdown, terms, and privacy links. Optionally pass couponCode to preview a server-validated discount without reserving usage.
• create_asset_uploads — Allocate temporary upload slots. This writes records but does not purchase a product.
• create_order_intent — Claim uploaded artwork and record confirmed delivery details and customer consent. Returns a payment URL, amount, digest, expiry, and private status capability; it does not sign a payment.
• get_order_status — Read one intent’s payment and fulfillment state using its status capability. It does not expose the delivery address or contact details.

Current scope: one physical deck per order, direct delivery to U.S. addresses, and only products returned by the live catalog. Coupons are supported through the optional couponCode on get_product_configuration and create_order_intent. Digital downloads, store pickup, multi-deck quantities, cancellations, and refunds are not MCP tools. Artwork must already be rendered; the server does not turn source photos into finished card fronts. A separate trusted wallet/client must support the returned x402 v2 payment rail. Configured payments do not guarantee that a particular wallet client can sign them.

https://photomatchfun.com/api/mcp

Transport: remote Streamable HTTP, stateless, with JSON responses. No PhotoMatchFun login, API key, OAuth flow, or global Authorization header is required to connect or discover products. Use an MCP client rather than opening the endpoint as a web page. Clients limited to local stdio or the older HTTP+SSE transport need their own compatible bridge; no bridge is supplied here.

Authorization is scoped to individual operations: binary uploads require the slot’s Authorization: Bearer uploadToken; order creation requires each assetId and separate claimToken; status requires intentId and statusToken. HTTP status requests use Authorization: Bearer statusToken. Keep these values private. Never send wallet private keys, seed phrases, card numbers, or CVCs.

Desktop and server clients can connect without an Origin header. Browser-origin requests must come from a server-approved origin; arbitrary cross-origin browser clients are not supported. A 403 Origin is not allowed response requires an approved integration origin, not a PhotoMatchFun password.

VS Code supports this remote HTTP configuration. Use Install in VS Code above, or merge the following entry into .vscode/mcp.json in your workspace. Preserve any existing servers. The installation shortcut opens VS Code’s installation flow; review the endpoint and its trust prompts before enabling tools.

{
  "servers": {
    "photomatchfun": {
      "type": "http",
      "url": "https://photomatchfun.com/api/mcp"
    }
  }
}

• Run MCP: List Servers from the Command Palette, select photomatchfun, and start it.
• Open chat and enable the PhotoMatchFun tools in the tool picker. Ask it to list available products without creating an order.
• Expect five tools, including list_products and get_order_status. If tools are missing, inspect the server output and verify your organization permits remote MCP servers.

Alternatively, with the code command installed, run this command in a POSIX shell to add the server to your user profile:

code --add-mcp '{"name":"photomatchfun","type":"http","url":"https://photomatchfun.com/api/mcp"}'

Other clients that implement Streamable HTTP can use the same endpoint in their remote-server settings. Configuration key names are client-specific; the VS Code servers/type format is not a universal MCP configuration file.

• VS Code configuration and setup
• Official VS Code installation URL format

With Node.js 20 or later, install the SDK in a project directory, save the JavaScript below as smoke.mjs, and run it. It only discovers tools and reads the catalog; it creates no upload slots, orders, or payments.

npm install @modelcontextprotocol/sdk
node smoke.mjs

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "photomatchfun-quickstart", version: "1.0.0" });
try {
  await client.connect(new StreamableHTTPClientTransport(
    new URL("https://photomatchfun.com/api/mcp")
  ));
  console.log("Tools:", (await client.listTools()).tools.map(tool => tool.name));
  const result = await client.callTool({ name: "list_products", arguments: {} });
  if (result.isError) throw new Error(JSON.stringify(result.content));
  console.log(JSON.stringify(result.structuredContent ?? result.content, null, 2));
} finally {
  await client.close();
}

Verification on September 9, 2026: the official JavaScript SDK 1.30.0 connected to the public endpoint without credentials and read the five tools, two resources, workflow prompt, and live catalog. VS Code configuration and installation-link syntax were checked against Microsoft’s documentation; the VS Code graphical installation flow was not exercised. This connection check does not certify wallet signing or a paid fulfillment run.

Sample excerpt from list_products structuredContent on that date (not a current quote; re-read the catalog and product configuration for every order):

{
  "products": [
    {
      "productId": "photomatchfun-custom-photo-card-deck-delivery",
      "total": "24.98",
      "currency": "USD",
      "renderedPhotoFrontsRequired": 8,
      "available": true
    }
  ],
  "next": "Call get_product_configuration before rendering or uploading artwork."
}

Successful tools return structuredContent and readable JSON text in content. Tool failures can return isError: true even when the HTTP transport succeeded. Treat an empty catalog or configured: false payment rail as unavailable; do not invent a purchasable product.

• Show me the available PhotoMatchFun decks, their current total prices, and the artwork requirements. Do not create an order yet.
• Check the current product configuration and help me prepare the required card fronts. Show me the artwork, delivery details, total, terms, and privacy notice for confirmation before creating an order intent.
• Check the status of my existing order using the intent ID and status capability I supplied privately. Do not create a new order or payment.

MCP also exposes the purchase_photo_matching_game prompt and the resources photomatchfun://commerce/guide and photomatchfun://commerce/x402. The latter reports the current public payment configuration.

• Discover a live product, then call get_product_configuration with its productId and optional couponCode. Read server-issued prices and dimensions afresh. A quote does not reserve coupon usage; eligibility and pricing are checked again at intent creation.
• Have the customer review the product, complete artwork, total, U.S. delivery details, terms, and privacy notice. Record their actual consent with termsAccepted: true, acceptedAt as an ISO timestamp, and source: customer; never infer consent from a tool result.
• Render exactly the required number of complete card-front canvases. Call create_asset_uploads with productId and count; PUT one JPEG, PNG, or WebP to each returned uploadUrl using its requiredHeaders. Preserve assetId and claimToken separately.
• Call create_order_intent with productId, an opaque idempotencyKey, customer name/email/phone/shippingAddress, customerConsent, the same optional couponCode, and the assetId/claimToken pairs. Reuse the key only for unchanged order inputs, including the coupon. Identical retries return the original frozen price without reserving another coupon use.
• Review the returned price, intentId, orderDigest, and expiresAt. After the customer authorizes payment, POST the returned paymentUrl. For positive totals, its HTTP 402 PAYMENT-REQUIRED header describes the discounted requirement. A trusted x402 v2 wallet signs it; repeat the same POST with PAYMENT-SIGNATURE. The MCP connection alone cannot sign a payment. If the intent returns paymentRequired: false and amountCents: 0, POST the same paymentUrl to explicitly confirm the free order; no wallet signature or transfer is required.
• A successful payment response is HTTP 200 or 202. Payment settles, or a zero-total order is explicitly confirmed, before submission to the print provider. Poll get_order_status with intentId and statusToken, backing off between requests. fulfilled means provider submission succeeded, not that the package has arrived. needsOperatorReview indicates support must intervene.

If settlement times out or its outcome is unknown, follow the same-payment retry instructions rather than signing a second authorization. Do not work around a wallet timeout by sharing its secrets with this service.

• Detailed artwork and ordering workflow
• x402 payment and retry guide

Use the same couponCode when previewing a product and creating its intent. Codes are normalized for case, spaces, and hyphens. Invalid, disabled, expired, not-yet-active, exhausted, pickup-only, or below-minimum coupons return an error; the server never silently falls back to full price.

{
  "name": "get_product_configuration",
  "arguments": {
    "productId": "photomatchfun-custom-photo-card-deck-delivery",
    "couponCode": "YOUR_COUPON_CODE"
  }
}

For create_order_intent, add couponCode alongside the normal customer, customerConsent, assets, productId, and idempotencyKey fields. Review the returned price.amount, price.amountCents, coupon.savings, and paymentRequired before authorizing the order. Client-supplied prices, percentages, and discount amounts are rejected.

Intent creation reserves coupon usage in the same transaction that claims artwork. Payment or free-order confirmation redeems that reservation once. Retries keep the original amount even if the coupon is later edited. Expired unpaid intents release their reservation when their status or payment URL is checked. Abandoned reservations otherwise become reclaimable on subsequent coupon use after 24 hours. An uncertain in-flight settlement must be recovered on the same intent.

There is currently no separate MCP connection or per-tool fee. Physical orders use the server-issued USD product and shipping total after validated coupon discounts. Positive totals settle through the exact x402 requirement in USDC; zero totals require no payment. Your model provider and wallet/network may have separate costs. Never hard-code the example price, recipient, or network. Read the current product configuration and payment requirement before each purchase.

• MCP transport: 100 requests per 10 minutes per observed client IP; maximum JSON request body 1 MiB. Clients behind shared egress can share a limit.
• Upload-slot creation: 48 calls per hour per client identifier (a hash derived from the client IP), not 48 individual slots.
• Binary uploads: 48 requests per hour per observed client IP. Maximum 12 MiB per image; exact dimensions and content types come from the product contract.
• Order-intent creation: 20 calls per hour per client identifier. Each order must use the exact product-required artwork count, within the schema limit of 1–12 assets.
• Upload/claim capabilities expire after one hour; unpaid order intents expire after 30 minutes. Use each returned expiresAt rather than a local estimate.
• HTTP limits return 429 and Retry-After; tool-level limits return an error with retry guidance. Back off on 503 or temporary unavailability. Do not retry invalid artwork or changed idempotency inputs unchanged.

Order creation sends the customer’s name, email, phone, U.S. shipping address, consent record, and artwork references to PhotoMatchFun. The pending order payload is encrypted at rest. Uploaded artwork is validated and re-encoded, and artwork plus delivery details are provided to the fulfillment provider when a paid order is submitted. Payment status can include a public wallet address and transaction identifier.

Capability expiry is an access deadline, not a promise that every copy of order or image data is deleted at that moment. Order records and provider processing follow the linked privacy and terms policies. Keep capability tokens, image URLs, and customer details out of public logs, shared prompts, and analytics. Your MCP client and model provider have their own data-handling policies.

• Privacy policy
• Terms
• Returns and refunds
• Contact support

This page and its Markdown version share the same source. /llms.txt is a concise navigation aid that points agents to the documentation. It is not universal agent registration and does not guarantee discovery, indexing, or support by a particular client.

• Clean Markdown version
• llms.txt
• Live commerce manifest
• The llms.txt proposal