Getting Started

MCP server

The agent-native quickstart. One npx command gives Claude, Cursor, Codex, or any MCP client callable tools for the whole flow — mint a shop, search the catalog, render a mockup, build a buy link.

Human reading this for your agent?

You don’t need this page yourself — the same flow over plain HTTP is on Get started. The MCP server exists so an agent can skip the HTTP and the docs crawl entirely. Agents can also fetch llms-full.txt — the complete docs as one plain-text file.

Add it to your client

No install, no API key, no signup — npx runs the published @snowcone-app/mcp package, and the server is self-contained.

bash

# Claude Code — one command, no install (npx runs it):
claude mcp add snowcone -- npx -y @snowcone-app/mcp

Claude Desktop, Cursor, Codex, and most other clients take the standard config block instead:

json

{
  "mcpServers": {
    "snowcone": {
      "command": "npx",
      "args": ["-y", "@snowcone-app/mcp"]
    }
  }
}

Confirm it actually connected. Restart or reconnect the client and check that snowcone_* tools appear (e.g. claude mcp list shows snowcone ✔). A registered-but-empty MCP connection fails silently — if no tools show up, re-add and restart rather than proceeding. Once connected, call snowcone_quickstart first.

The tools

Eight tools cover the whole journey — the same three values as everywhere else (a product code, an artwork URL, a Shop ID), exposed as calls instead of URLs you assemble by hand.

snowcone_quickstart

The whole model and the recommended tool order in one screen. Call this first — it also confirms the connection is live.

snowcone_mint_shop

Mint a sandbox Shop ID — no account or human needed. Mint once and reuse it; details on Get a Shop ID.

snowcone_claim_status

Poll whether your human has claimed the shop (to route the money to them).

snowcone_release_shop

Delete an unclaimed sandbox shop you minted, freeing your mint budget.

snowcone_search_catalog

Full-text search the public product catalog.

snowcone_get_product

Placements, mockups, and options for one product code.

snowcone_render_mockup

Build an <img>-ready mockup URL from a product + artwork + shop. By default it verifies the URL actually renders before handing it back.

snowcone_buy_url

Build the matching checkout URL from the same inputs.

Zero to buyable mockup

snowcone_quickstart tells the agent all of this itself, but here’s the shape of a session:

Mint a shop — once

snowcone_mint_shop returns a shop_id to reuse everywhere, plus a claim block for the human handoff. Minting is rate-limited, so mint once — not per attempt. Limits and lifecycle live on Get a Shop ID.

Pick a product

snowcone_search_catalog to browse, then snowcone_get_product for placements and options. BEEB77 is a known-good demo code.

Render the mockup

snowcone_render_mockup with the product code, the shop_id, and a publicly fetchable raster image URL. It verifies the render before returning, so a bad placement key or unusable asset is a clear error instead of a confident-but-blank image.

Sell it, then hand off

snowcone_buy_url builds the checkout link — live payments, with sales routing to the human once they claim. Give them claim.verification_uri_complete and poll snowcone_claim_status until it flips to claimed.

Point it at another stack

Everything defaults to production. Each host is overridable by env var, so the same server drives a local or staging stack unchanged:

bash

# Every host defaults to production; override any of them to drive a
# local or staging stack with the same server:
SNOWCONE_API_BASE=…    # api.snowcone.app
SNOWCONE_IMG_BASE=…    # img.snowcone.app (render)
SNOWCONE_BUY_BASE=…    # buy.snowcone.app (checkout)
SNOWCONE_MEILI_HOST=…  # catalog search host
SNOWCONE_MEILI_KEY=…   # catalog search key
SNOWCONE_MEILI_INDEX=… # catalog index name