Agent API & MCP guide

Connect an MCP client

Configure a remote Streamable HTTP connection to the URL below. Use a client that supports adding custom MCP servers. No private backend credential is required for these public, read-only tools.

https://readyimprint.com/mcp

With a current SDK, let the SDK negotiate the protocol. Older clients use the initialize handshake; newer protocol versions can use server discovery. The connection exposes tools for discovery and estimates. It does not expose customer records, saved orders, payment actions, or artwork approval. An endpoint connection does not register us automatically in a third-party shopping directory.

For direct protocol clients: let your MCP SDK establish the connection, then list and call tools. Use the negotiated protocol version and accept JSON and event-stream responses. This server uses stateless HTTP with JSON responses.

Discover before you quote

Availability follows this storefront’s enabled categories. Guided options cover selected product families; always inspect the returned coverage and notes. When a product has only partial option coverage, continue through its website configurator instead of guessing configuration values.

REST quote request

Use POST /api/quotes with Content-Type: application/json. The MCP quote tool calls this same pricing gateway, with an additional check that the product is currently enabled and that changes use its documented guided fields. REST also retains the storefront’s advanced metadata support; this does not make advanced fields available through MCP. Get current product identifiers and a configuration template through discovery rather than hard-coding an identifier from an example.

Save the returned quote template as quote.json, adjust only its supported selections and quantity, then request the estimate:

curl 'https://readyimprint.com/api/quotes' \
  -H 'Content-Type: application/json' \
  -c quote-cookies.txt -b quote-cookies.txt \
  --data-binary @quote.json

Configuration examples

Call get_product_options with one of these argument objects. Use its returned quote_template as request_quote arguments, setting the quantity shown. Availability is checked at runtime; patches, for example, may not be enabled on your storefront. Keep advanced template fields unchanged.

{
  "handle": "lanyard-polyester",
  "category": "lanyards"
}

{
  "handle": "can-cooler-collapsible",
  "category": "can-coolers"
}

{
  "handle": "wristband-debossed",
  "category": "wristbands"
}

{
  "handle": "table-cover-throw-polyester",
  "category": "table-covers"
}

{
  "handle": "patch-embroidered",
  "category": "patches"
}

The template selects a digital proof explicitly. Change the category’s proof flag to false only when that matches the customer’s choice. These examples are starting configurations, not descriptions of every available option.

Interpret the result

Amounts ending in _cents are integer US cents. The configuration subtotal is result.unit_cents × quantity + result.flat_fees_cents. A null unit price means unavailable, not zero; a resolved zero price remains possible. Breakdown amounts use dollars. The ladder contains at most six quantity comparisons for this configuration. A comparison’s per value is its unit price in cents; flat fees are separate. The ladder’s save value is the rounded percentage saved compared with the highest unit price among those returned rows, not a retail list price or the full catalog ladder.

This is an estimate, not a reserved price or checkout authorization. Requote after a selection or quantity changes. Delivery, any applicable tax and order-level charges, and final artwork details are handled in the ordering workflow. Do not describe the estimate as a confirmed delivered total.

Errors, limits & retries

200

Inspect result.error and result.unit_cents. A null unit price means no valid price was resolved; do not present it as zero.

400

The configuration or JSON is invalid. Correct the fields before retrying.

413

The request exceeds the 32 KB body limit. Send pricing selections only.

429

Rate limited. Wait for Retry-After before retrying; do not rotate cookies or identities.

503

Pricing is temporarily unavailable. Retry with backoff; do not substitute an old estimate as a current quote.

Quotes use shared session, network, and service-wide limits. Keep the returned session cookie when your client supports it. Requests from the same network share a ceiling even when cookies change. Current quote ceilings are 120 requests per session per minute, 240 per network per minute, and 1,200 service-wide per minute. Discovery has a separate process-local limit of 60 calls per network per minute, bounded search pages of 20 products, and a short catalog cache. Process-local discovery limits reset on restart and are not a global cross-replica quota. Limits are ceilings, not guaranteed capacity; respect Retry-After.

MCP may represent a failed tool call as an error result within a successful protocol response. Check the tool’s isError flag and message, not only the HTTP status. Browser origins are checked; an invalid Origin receives HTTP 403.