For shopping agents

Doors for shopping agents

Six read-only tools and three feeds let an assistant find a piece, see the sizes its file was measured to hold, and quote the price checkout will charge. No key, no account.

Checkout is closed. Until it opens the three feeds list no offers, on purpose: an offer an agent cannot buy is not an offer. Search, sizes and quotes work now.

JSON-RPC 2.0 over HTTP · protocol 2025-06-18

MCP server

POST https://www.painted.agency/api/mcp. Single calls, no batches, no session, 60 requests a minute per address. Every tool is annotated read-only, not destructive and closed-world.

curl -s https://www.painted.agency/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

search_artworks: Search the catalogue by words and facets. Returns wall-label summaries with the sizes each piece is offered at. Facet ids come from list_categories.
get_artwork: One piece: its full wall label, the object note, every size that passed the print check with measured dpi and grade, the sizes that failed and why, and published prices.
list_categories: The catalogue map with piece counts: subjects, styles, rooms, colours, moods, media, houses, price bands and print sizes. Use the ids as search_artworks filters.
quote_price: The price of one piece at one size, format and frame, as checkout will charge it before shipping and tax. Refuses a size the piece is not offered at.
recommend_for_room: Pieces tagged for a room, each with the largest offered size that fits the wall. Give the wall width in inches to size them; without it the largest offered size is returned.
travel_styles: The poster traditions, places and featured cities of the Travel section, with the URL of the studio where a visitor makes a poster of any city.

Add it to Claude Code:

claude mcp add --transport http painted-agency https://www.painted.agency/api/mcp

Search for golf art for a study:

curl -s https://www.painted.agency/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_artworks","arguments":{"query":"golf","room":"study","limit":3}}}'

One piece, with every size it passed the print check at:

curl -s https://www.painted.agency/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_artwork","arguments":{"id":"blackheath-golfer-1790"}}}'

The price checkout will charge for one size and format:

curl -s https://www.painted.agency/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"quote_price","arguments":{"id":"blackheath-golfer-1790","size":"8x12","format":"paper","qty":1}}}'

Pieces for an 84-inch living-room wall, each at the widest size that fits:

curl -s https://www.painted.agency/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"recommend_for_room","arguments":{"room":"living-room","wall_width_in":84,"limit":4}}}'

agent-feed@1

Agent feed

The fleet’s agent-feed@1 contract: schema.org Products with one Offer per sellable format and size, each carrying the exact checkout line to post. Pieces with nothing sellable are absent, never flagged. The server is the only price authority, and a cart line carrying a price is refused. Deterministic: the same catalogue gives the same bytes.

curl -s https://www.painted.agency/.well-known/agent-feed.json

OpenAI JSONL · Google Merchant RSS

Product feeds

One row per sellable piece, format and size, the stock id as mpn, the studio or house as the brand. The OpenAI feed follows the commerce product-feed spec; the Google feed is Merchant Center RSS 2.0.

curl -s https://www.painted.agency/feeds/products.jsonl | head -n 3

curl -s https://www.painted.agency/feeds/google.xml

Plain text

llms.txt

What the site is, how to search it, every door on this page, and the policies, with counts computed from the catalogue.

curl -s https://www.painted.agency/llms.txt

The rules

Every price comes from the server. Never state one these doors did not return.
A size that is absent failed the print check. It is not out of stock, and it is not coming back at a lower grade.
No tool places an order or takes payment. A person checks out on this site and pays on Stripe.
Policies an agent may quote: terms, returns, shipping, privacy.