within

npx add-mcp 'https://shopwithin.co/mcp'

within runs a free, remote MCP server at https://shopwithin.co/mcp. Point an assistant, an app or your own code at it, and it can read the live shelves of independent luxury boutiques: what is in stock right now, in which sizes, at what price, at which shop, and the page where a shopper buys it. There is no account and no key, and all twenty-six tools only read. The same tools answer over plain HTTPS at https://shopwithin.co/api/v1, described at https://shopwithin.co/openapi.json, for the apps and connector platforms that take an API and a spec rather than an MCP endpoint.

Updated 10 November 2026

What the server is, and what it is not

It is a Model Context Protocol (MCP) server that you reach over the internet. It reads the same shelves the site shows. Those come from each boutique's own register, its point of sale, so the sizes and stock are the shop's own. An agent and a person asking the same thing get the same answer.

It is not:

• A checkout. No tool adds to a bag, holds a piece or takes a payment.
• A search of the whole web. It reads only the boutiques that sell on within, never mass market stores.
• A style adviser. It says what is on the shelf, not what to wear.
• A package to install. Nothing runs on your computer; you connect to a web address.
• A way into anyone's account. It never sees a shopper's saves, bag or orders.

The endpoint

Address

https://shopwithin.co/mcp

Protocol

Model Context Protocol over Streamable HTTP, stateless, JSON responses. It speaks the protocol versions 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05 and 2024-10-07.

Requests

One JSON-RPC message per POST. Send accept: application/json, text/event-stream; a request that does not accept both gets a 406. There is no session, so you can call tools/list or tools/call without an initialize first.

Other methods

A plain GET answers a short JSON description: the name, the version, the endpoint and the tool names. DELETE answers 405, because there is no session to end.

Browsers

CORS is open to every origin, so code in a web page can call it. Answers are never cached (cache-control: no-store).

Server card

https://shopwithin.co/mcp/server-card, in the MCP server card format: the name, the version, the endpoint and the protocol versions, for apps and lists that look a server up before they connect.

Account and price

No account, no key, free.

Resources

within://about (one paragraph on within and its tools), within://guides (the journal's city and field guides, one per line) and within://guides/{slug} (one guide in full).

Limits and rate limits

• Each address gets a burst of 60 requests, then one a second as the burst refills. All callers together get a burst of 1,200, then 20 a second.
• Past the limit the answer is HTTP 429 with {"error":"rate_limited"} and retry-after: 30.
• A page of results holds 1 to 24 pieces, 12 if you do not say. offset runs to 480, so one search reaches about 500 pieces.
• A query is 200 characters at most. brands, categories, sizes and boutiques take up to 10 values each.
• visual_search takes JPEG, PNG or WebP under 1.5 MB. A linked image must arrive within 8 seconds, and private or local addresses are refused.
• Descriptions are cut at 1,200 characters. Facets show the top 8 values of each kind.
• Prices are never converted. Each piece says its currency.
• Stock is as fresh as the boutique's last sync, and every piece says when that was.

The twenty-six tools

Every tool is marked read only and safe to repeat. Only visual_search reaches outside within, to fetch the photo or the post a shopper gives it. Every answer comes twice: a short text an assistant can quote whole, and structuredContent with the fields below. Most tools answer with pieces, and a piece always has these fields:

id, boutique_domain

together, the piece's name in every other tool

title, brand, category

as the boutique lists them

price, price_max, currency, price_label

price_max only when sizes are priced differently; price_label reads like CAD 1,500

sizes_in_stock, units_in_stock

the sizes on the shelf now, and how many pieces in all

boutique

domain, name, neighbourhood, city and its page on within

collect_in_store, delivery

whether the piece can be picked up at the counter or delivered

image, url

the main photograph, and the shopwithin.co page where the shopper buys

price_drop

the earlier price and the day it changed, when the piece is marked down

condition

new, pre-owned, lightly-used, worn-once or vintage, or empty when the shop does not say

search_pieces: search the shelves

Finds pieces in stock right now: clothing, shoes, bags, jewellery, watches and objects. A plain sentence works as the query, and prices in it such as "under $400" or "cheapest" are understood. With no arguments it returns the current front shelf. Every answer carries live sizes, the price in the boutique's currency, the shop and the page to buy.

Ask Black leather loafers in a 42, under 600 dollars, in Toronto.

Takes

• query: what the shopper wants, up to 200 characters
• brands, categories, sizes, boutiques: lists of up to 10 values each; boutiques are domains such as wdlt117.myshopify.com
• city: only boutiques in that city
• department: women or men
• price_min, price_max: in the boutique's currency
• sort: relevance, newest, price_low_to_high or price_high_to_low
• lens: new, trending or sale, to browse a shelf instead of searching (ignored when a query or a filter is given)
• limit: 1 to 24 pieces, 12 if you leave it out; offset: 0 to 480

Returns pieces (the piece record below), total, total_is_floor, next_offset, facets (the top 8 brands, categories, sizes and boutiques with counts), related_searches (label, query, count), view_url (the same shelf on shopwithin.co) and note (how the sentence was read, for example: Understood as: searched for "rick owens boots", priced up to 1500).

A city with no boutique gets an empty answer that says so and names the cities that have boutiques. Sizes are matched by the label each shop prints; when nothing matches exactly, a bare number such as 42 matches that number in any size system, and no conversion is implied.

get_piece: one piece in full

Everything about one piece: the description, every size with live stock, the photographs, the price and any markdown, pickup in the shop or delivery, the boutique, the page to buy, and a few pieces in the same vein.

Ask Check this jacket is still there in a medium (with a shopwithin.co product link).

Takes

• url: a shopwithin.co/product/... link, or
• boutique_domain and id: from any earlier result

Returns found, piece (the piece record plus description up to 1,200 characters, images, tags, variants with label, price, compare_at_price, in_stock and units, collect_at, and rating with average and count) and similar (up to 6 pieces).

A piece that has sold, or an old link, answers found: false with a plain sentence, never a guess.

piece_fit: how one item fits

How one item fits, before anyone picks a size: its own measurements (the boutique's, or the designer's garment chart for that style), the designer's body chart, notes on how it runs, the model's size and height, which sizes are in stock, and a short answer for each size the size guide covers (up to ten, in stock or not). Give the size the shopper wears in other clothes, in any system, and the answer repeats it with a note to look at the rows nearest it.

Ask I usually wear an IT 48. Which size of this jacket should I get?

Takes

• url: a shopwithin.co/product/... link, or
• boutique_domain and id: from any earlier result
• usual_size: optional, the size the shopper usually wears, as they say it, such as M, IT 48, US 9 or 32 waist

Returns found, piece (the piece record) and fit (notes, measurements, printed, body, model, foot, dimensions, answers (a short answer for each size the size guide covers, up to ten), journal and page).

When the boutique and the designer give no measurements, chart or fit note, the answer says so plainly instead of guessing.

list_boutiques: the boutiques on within

The independent luxury boutiques on within, by city, with what each has on the shelf and its hours. The domain it returns names a boutique in every other tool.

Ask Which boutiques in Toronto carry Rick Owens, and can I collect today?

Takes

• city: optional, only boutiques in that city

Returns boutiques (domain, name, neighbourhood, city, pieces_live, currency, hours, collect_in_store, delivery, collect_ready_in_minutes, url) and cities (every city with a boutique).

hours is empty when the shop has not given them. To answer the Rick Owens half, an agent follows with search_pieces and brands set to Rick Owens.

boutique_shelf: one boutique's shelf

One boutique's shelf right now, newest first, with sizes and prices. A query searches inside that shop only.

Ask What does WDLT117 have from MM6 Maison Margiela right now?

Takes

• boutique_domain: required, as list_boutiques or any piece shows it
• query: optional, searches inside the shop
• limit: 1 to 24, 12 if you leave it out; offset: 0 to 480

Returns boutique (as in list_boutiques), pieces, next_offset and view_url.

An unknown domain gets an answer that says so and lists the boutiques that are on within.

convert_size: a size in every other system

Turns a ring, shoe, clothing, suit, belt or hat size into every other system, or reads one designer's own chart. It answers only from the tables on the size pages, where every row comes from a named source with the day it was read, and it returns the page that shows the answer. Called without from and size, it lists the systems and tables it has.

Ask I wear a UK N ring. What is that in US sizes?

Takes

• kind: rings, shoes, clothing, suits, belts or hats, or designer: a designer's slug such as nike
• from: the system the size is written in, such as us, uk or eu
• size: as printed, such as 7, N 1/2, 42 or M
• to, department (women or men), table: optional, to narrow the answer

Returns status (answered, nearest, out-of-range, bad-system, bad-size, no-match or need_input), scope, systems, tables, matches (each table's row in every system), sources (publisher, url, read_on), page_url, size_page_url, note, kinds and designers.

estimate_duty: duty and tax at the door

Works out what a piece costs at the door when it is shipped to the US, Canada, the UK or Australia: the duty, any extra tariff on the country it was made in, the tax, the government and carrier fees, and the total. Every line names its official source and the day it was read, and the answer links the duty calculator page that shows it.

Ask What will I pay at the door for a 1,295 dollar wool coat made in Italy, shipped from Canada to the US?

Takes

• to: us, canada or uk
• price and currency: CAD, USD, GBP or EUR, without shipping
• kind: one of 47 kinds, such as coat-wool, sneakers-leather, bag-leather or watch-automatic
• made_in and ships_from: two letter country codes such as IT and CA
• department, ship_by (fedex, courier or post; royalmail or parcelforce for the UK), region (a Canadian province), shipping, weight_kg, usmca: optional

Returns found, to, currency, status, value, lines (label, detail, amount, sources), owed_before_delivery, tax_at_checkout, total, what_changes_it, notes, exchange_rate_date, estimate_note and page.

It is an estimate from the rules on the page. The carrier's bill is the final word.

find_notes: within's own guides

within's own writing for a question: the journal's guides and notes (how a designer's sizes run, a city's shops, what to wear to what, a season's coats) and the edits (items picked around one idea). Ask in plain words; up to five come back, each with its link.

Ask How do Margiela Tabis run?

Takes

• query: the question in plain words, 2 to 200 characters
• limit: 1 to 8, 5 if you leave it out

Returns notes, each with kind (note or edit), title, line and url.

When nothing matches, the answer says so and suggests searching the shelves instead.

new_arrivals: just in: new arrivals

The newest clothes, shoes, bags and jewellery to arrive at the boutiques, newest first. It reads live stock, so an item that sold out is not in the answer.

Ask What just came in from Rick Owens?

Takes

• designers, categories, boutiques: lists of up to 10 values each
• department: women or men
• city: the city the boutiques are in
• price_max: in the boutique's currency
• limit: 1 to 24 items, 12 if you leave it out; offset: 0 to 480

Returns pieces (the piece record), total, next_offset, view_url (the same list on shopwithin.co) and note.

A city with no boutique gets an answer that says so and names the cities that have boutiques.

on_sale: on sale now

Designer clothes, shoes and bags marked down right now, each with its old price, the price now and how much is off. It checks every item itself, so nothing in the answer is at full price. When within has a sale page or a Black Friday page for the designer, the answer gives it.

Ask What is on sale from Canada Goose right now?

Takes

• designers, categories, sizes, boutiques: lists of up to 10 values each
• department: women or men
• city: the city the boutiques are in
• price_max: in the boutique's currency
• order: biggest_drop, lowest_price or newest
• limit and offset, as in search_pieces

Returns pieces (the piece record plus was_price, amount_off, percent_off and the day the price dropped), total, total_is_floor, next_offset, pages (within's sale pages for the ask), view_url and note.

It only knows what the boutiques on within have marked down today.

pickup_today: pick up in a shop

Items a shopper can buy on shopwithin.co and pick up in the shop, at the boutiques that offer pickup. Each comes with the shop and its street, and the shop's hours where we hold them.

Ask What sneakers can I pick up in Toronto today?

Takes

• city: the city the shops are in
• query: what the shopper wants
• designers, categories, sizes: lists of up to 10 values each
• department: women or men
• price_max: in the boutique's currency
• limit and offset

Returns pieces (the piece record plus pickup), shops (address, hours, whether it is open today), next_offset, view_url and note.

It says a shop is open today only where we hold that shop's hours.

wear_with: what to wear with it

The clothes, shoes, bags and accessories in stock that go with one item: the same ones its page on shopwithin.co shows in its Wear with row. Each comes with the part of the outfit it is.

Ask What goes with this jacket? (with a shopwithin.co product link)

Takes

• url: a shopwithin.co/product/... link, or boutique_domain and id from an earlier result
• department: women or men
• limit: how many items

Returns found, item (the item asked about), pieces (the piece record plus part, such as the coat, the jeans or the bag) and note.

delivered_price: what an item costs delivered

What one item costs at the door in a country: the item's price, the boutique's own delivery price to that country, and an estimate of the duty, tariffs, tax and fees, added up. The duty estimate covers the United States, the United Kingdom and Australia, and Canada adds sales tax by province. For other countries the answer is the item and the delivery, and it says what is missing.

Ask What will this coat cost delivered to New York, with duty? (with a shopwithin.co product link)

Takes

• url: a shopwithin.co/product/... link, or boutique_domain and id
• country: where it is delivered, a name or a two letter code
• region: the province or state, for Canadian sales tax
• made_in: two letter code of the country it was made in, when the page does not say
• kind: what the item is, when the page does not say

Returns found, item, country, ships, price, delivery (amount, days, the price it ships free from), sales_tax, duty (each line with its source), total (amount, currency and whether it is complete), missing and estimate_note.

It is an estimate. The carrier's bill is the final word. A country the boutique does not ship to gets a plain answer.

compare_pieces: compare items side by side

Two to four items side by side: name, designer, price and currency, condition, sizes in stock, the shop and its city, pickup and delivery, a line from the description, and any other boutique that has the same item. Then what differs between them.

Ask Which of these two is cheaper, and which has a 43? (with two shopwithin.co product links)

Takes

• pieces: 2 to 4 entries, each a shopwithin.co/product/... link or a boutique_domain and id

Returns pieces (the piece record plus description and also_at), not_found, differences (plain lines) and note.

Prices stay in each boutique's own currency and are never converted.

designer_guide: one designer: facts, stock and stockists

One designer or brand in one answer: who founded it, when, where it is from, who owns it and where it is made, each fact with its source. Then how many items the boutiques have in stock right now, which kinds, the price range and how many are pre-owned; the boutiques that stock it; the designer's own stores where known; how its sizes run; the common questions; and its pages on shopwithin.co.

Ask Who owns Chrome Hearts, and where can I buy it?

Takes

• designer: the name or its slug
• city: adds the boutiques in that city that list the designer on their own sites

Returns found, designer, about (text and sources), in_stock (items, boutiques, kinds, prices, pre_owned_items), boutiques_on_within, directory (the city's shops that list it), own_stores, sizes, questions (each with its answer and sources), pages and nearest (close names when the designer is not known).

It only knows what shopwithin.co holds. A fact with no source on the site is left out.

where_to_buy: where to buy it

Where to buy a designer, a named item or a style code. First the items in stock right now, each with the shop, the price, the sizes and the page to buy. Then, with a city, the boutiques there that list the designer on their own sites, with their streets. Then the designer's own stores where shopwithin.co holds a sourced answer.

Ask Where can I buy Guidi boots in Melbourne?

Takes

• query: the designer, the item or the style code
• designer: the designer's name, when the query is an item
• city: stock from boutiques there, and the shops there that list the designer
• country: a two letter code, for boutiques that deliver there
• size: a size that must be in stock

Returns query, designer, pieces (the piece record), exact, total, directory (the city's shops that list it), directory_cities, own_stores, view_url and note.

If nobody has it, the answer says so.

price_check: what it costs right now

What a designer's item costs right now across the boutiques: how many are in stock, the lowest, middle and highest price, pre-owned against the rest, the cheapest few with their shops and links, and within's own price page for the designer.

Ask How much is a Chrome Hearts hoodie?

Takes

• query: the designer and the item
• designer, category: to narrow it
• condition: pre-owned or new
• size: a size that must be in stock
• price_max: in the boutique's currency

Returns query, understood (how the ask was read), found, in_stock, boutiques, prices (lowest, middle and highest for each currency), by_condition, pieces (the cheapest few), compared_with (a second designer, when two are named), pages, view_url and counted_on.

Prices stay in each boutique's own currency and are never converted.

brands_like: similar brands

Designers like a given one, counted from live stock: the brands the same boutiques stock and whose items are the same kinds, most alike first. Each comes with how many items are in stock and what it shares with the one asked about.

Ask Which brands are like Rick Owens?

Takes

• designer: the name or its slug
• limit: how many to return

Returns found, designer, similar (name, url, items, shared_boutiques, shared_kinds), how (how the list was made) and nearest.

The list says what the same boutiques stock today. It is not a judgement of taste, price or look.

boutique_directory: find boutiques in a city

Independent boutiques and clothing stores in a city, from within's directory of shops in more than 140 cities. Each shop comes with what kind of shop it is, its street and neighbourhood, a few designers it stocks, its page on shopwithin.co, and whether it sells on within.

Ask Which vintage stores are in Paris?

Takes

• city: the city the shops are in; a part of a city works too
• country: a name or a two letter code, to search every city in it
• neighbourhood: one part of the city
• kind: the kind of shop, such as vintage, consignment or sneakers
• designer: only shops that stock this designer
• name: a word in the shop's name
• limit and offset

Returns boutiques (name, kind, street, neighbourhood, city, country, designers, url, sells_on_within and, for the ones that do, domain), total, next_offset, place, neighbourhoods, kinds, cities, covered (the countries and cities in the directory) and view_url.

The list is A to Z, not ranked. Most shops in it do not sell on within, and it holds no ratings or reviews. With no city it lists the cities covered.

boutique_details: one boutique: address, hours, designers

One boutique from the directory: what kind of shop it is, its address and neighbourhood, its opening hours with the day they were read, its website and Instagram, the designers its own site lists, and its page on shopwithin.co. For a boutique that sells on within it adds how many items are live.

Ask Where is Miami Twice, and when is it open?

Takes

• name: the shop's name
• city: when two shops share the name
• url: the shop's directory page on shopwithin.co, in place of the name

Returns found, boutique (name, kind, about, address, neighbourhood, city, country, hours, website, instagram, designers, url, sells_on_within, domain, items_live), matches (when more than one shop has the name) and stockists.

Hours are held for some shops only. It holds no phone numbers, ratings or reviews.

delivery_and_returns: delivery, pickup and returns

Delivery, pickup and returns for the boutiques that sell on within. For one boutique: what delivery to a country costs and how many days it takes, the price an item ships free from, the countries it ships to, pickup in the shop, and its return terms, each with the boutique's own page it was read from. With no boutique it gives one line per boutique for the country.

Ask Does WDLT117 ship to the US, and can I return it?

Takes

• boutique: the boutique's domain or its name
• country: where it is delivered, a name or a two letter code

Returns boutiques (name, city, currency, ships_to_country, delivery, ships_to, local_delivery, pickup, returns, url, policies_url), country and note.

Delivery prices are before duty and tax. It covers the boutiques on within only.

gift_ideas: gift ideas

Gift ideas in stock: gifts for her, for him or for anyone, under a budget, plus within's gift guides that fit. The gifts come from those guides, where every item is listed in one size: jewellery, wallets, bags, hats, scarves, sunglasses, watches and candles.

Ask Gift ideas for my dad under 300 dollars.

Takes

• recipient: who it is for, such as her, him, mom or boyfriend
• budget: the most to spend
• kind: a kind of gift or a word
• limit: how many items

Returns pieces (the piece record), source (a guide, or plain stock under the budget), gift_for, budget, budget_currency, total, guides (title, about, url) and note.

When the guides hold too little for the ask, it returns plain stock under the budget and says so.

outfit_ideas: outfit ideas

Outfits within has already put together, for a question or an occasion in plain words: its edits, its outfit pages and its looks, each a whole outfit. Up to five come back, each with the items in it that are in stock.

Ask What should I wear to the ballet?

Takes

• query: the question or the occasion
• department: women or men

Returns results (kind, title, about, url and items with price and link), department, hub_url and note.

It returns only what is on within and gives no advice of its own.

The same tools over plain HTTPS: the REST API

Some connector platforms and agents take an API address and an OpenAPI document rather than an MCP endpoint. For them every tool is also a path under https://shopwithin.co/api/v1, with the same arguments, the same validation and the same answer. A GET takes its arguments as a query string (lists comma separated); POST takes a JSON object. Every answer is JSON with ok, tool, text (the short passage an assistant can quote) and data (the structured answer the tool's output schema describes).

OpenAPI

https://shopwithin.co/openapi.json, version 3.1, built from the tools' own schemas so it never drifts from them.

Paths

GET /pieces (search_pieces), GET /pieces/{boutique}/{id} (get_piece), GET /pieces/{boutique}/{id}/similar (similar_pieces), GET /pieces/{boutique}/{id}/fit (piece_fit), POST /visual-search (visual_search), GET /boutiques (list_boutiques), GET /boutiques/{boutique}/shelf (boutique_shelf), GET /trending (trending_now), GET /sizes/convert (convert_size), GET /duty/estimate (estimate_duty), GET /notes (find_notes), GET /new-arrivals (new_arrivals), GET /sale (on_sale), GET /pickup (pickup_today), GET /pieces/{boutique}/{id}/wear-with (wear_with), GET /pieces/{boutique}/{id}/delivered-price (delivered_price), POST /compare (compare_pieces), GET /where-to-buy (where_to_buy), GET /prices (price_check), GET /designers/{designer} (designer_guide), GET /designers/{designer}/similar (brands_like), GET /directory (boutique_directory), GET /directory/boutique (boutique_details), GET /delivery (delivery_and_returns), GET /gifts (gift_ideas), GET /outfits (outfit_ideas). GET /tools lists every tool with its schemas, and POST /tools/{tool} calls any tool by name.

Example

https://shopwithin.co/api/v1/pieces?query=black+leather+loafers+under+600&sizes=42&city=Toronto

OpenRPC

https://shopwithin.co/mcp/openrpc.json describes the MCP tools as JSON-RPC methods, for the lists that want that form.

Commerce profile

https://shopwithin.co/.well-known/ucp is within's business profile in the Universal Commerce Protocol, naming the catalog service (search, lookup, product) at https://shopwithin.co/ucp/v1.

Limits and door

The same as the MCP endpoint: no account, no key, a burst of 60 requests per address, then one a second.

How a shopper buys a piece the agent found

1. The agent searches and shows the pieces, each with its url on shopwithin.co.
2. The shopper opens that page, which reads the sizes and stock again, fresh.
3. They pick a size and tap Buy.
4. within hands the bag to the boutique's own checkout. Every boutique on within today sells through its own online shop, so the shopper pays the boutique there, at the boutique's own price.
5. The boutique ships the piece or holds it at the counter for pickup. Where it ships, what shipping costs and when a piece is ready to collect all show at checkout.

Nothing is reserved or charged through the tools: every piece carries its shopwithin.co page, and the boutique's own checkout does the rest. This is the finding half of agentic commerce. The paying half stays between the shopper and the boutique, and the boutique keeps its customer.

What it never does

It never takes a payment, holds a card, or places an order. It never stores a photograph: an image sent to visual search is matched in memory and discarded. It never invents a size, a price or a stock level; when nothing matches, it says so.

• It never shows a test shop or a demo showroom, only boutiques that sell on within.
• It never writes anything. No tool changes a bag, a save, a price or a shelf.
• It never asks for a name, an email or a login.
• When a city has no boutique yet, it says so and names the cities that do.

How to connect

From an assistant app

Open its settings, find connectors, add a custom connector, and paste https://shopwithin.co/mcp. No key or account is needed. If it asks for a name, use within.

From a command line

Add a remote MCP server named within, transport HTTP, at the endpoint. Most command line agents take it in one line of this shape:

<your-agent> mcp add --transport http within https://shopwithin.co/mcp

From a code editor

Add it to the editor's MCP settings file. Most editors read this shape:

{
  "mcpServers": {
    "within": {
      "url": "https://shopwithin.co/mcp"
    }
  }
}

Some editors also want a type of http beside the url. The server answers the same way.

As a local command

Some apps only start an MCP server as a command on your computer. For those there is a small bridge on GitHub. It passes each request to the server above and gives the same twenty-six tools. It needs Node 18 or newer:

{
  "mcpServers": {
    "within": {
      "command": "npx",
      "args": ["-y", "github:startupbuilders777/within-mcp"]
    }
  }
}

The bridge, every tool written out in full, settings files to copy and the plugin are in the repo: github.com/startupbuilders777/within-mcp.

From your own code

Any MCP client library connects the same way, or you can send JSON-RPC yourself. To list the tools:

curl -s https://shopwithin.co/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

To call one:

curl -s https://shopwithin.co/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
        "name":"search_pieces",
        "arguments":{"query":"black leather loafers under $600","sizes":["42"],"limit":3}}}'

In an app that shows widgets

Search, piece and shelf answers come with a widget, ui://widget/within-shelf.html, that shows the results as a shelf of photographs, each with its price, its sizes, its shop and a link to buy on within.

Who it is for

• People who shop with an assistant and want real stock at real shops, with the page to buy.
• Developers building a shopping agent, a personal shopper, a gift finder or a style app who need live boutique stock without scraping shop sites.
• Anyone who wants a size conversion or a duty estimate with its source named.
• Boutiques that want their shelf to answer wherever their customers ask.

Who it is not for

• Buying inside the chat. There is no checkout tool; the shopper buys on the boutique's page.
• Comparing prices across the whole web or mass market stores. It reads only the boutiques on within.
• Bulk copying or a product data feed. The limit is one request a second per address.
• Style advice with no shopping in it.
• Apps that need a shopper's account, orders or saved pieces. None of that is exposed.

The pages an agent can cite

The tools read the shelves. These pages answer the rest, one kind of page per line, each at its own address.

• Trending: the chart of designer pieces trending at boutiques this week, updated daily, each piece with its reason and its place last week; the designers trending this week at /trending/designers, each with a page of its pieces; the women's and men's charts at /trending/women and /trending/men; one page per kind of piece, for example /trending/sneakers and /trending/women/bags; one page per past week at /trending/week; the same chart as data at /trending.json and as a feed at /trending/feed.xml.
• Designers, for a reader anywhere: one page per designer, with the boutiques that hold it today, the count, the prices and how it reaches you. Every designer has one at /designers/{designer-slug}, and the A to Z is at /designers.
• Sneakers: every pair on the shelves, then one page per line and one per model, new and pre owned, for example /shop/toronto/sneakers/jordan-1.
• Winter jackets and parkas: every winter coat on the shelves, warmest first by each maker's own rating, with the makers side by side.
• Comparisons: SSENSE, Farfetch and other designer sites side by side for Canada and the US (duty, returns and who takes your card), from each site's own pages: /compare/ssense-alternatives, /compare/farfetch-alternatives and /compare/ssense-vs-farfetch.
• Cities: one page per city the boutiques deliver to, with the designers people there look for and the pieces in stock, for example /city/new-york.
• Prices: what each designer costs on the shelves today, with the range, the middle price and the count, for example /guides/prices/chrome-hearts.
• Sale: designer pieces marked down today, across every boutique.
• Black Friday: the deepest markdowns at the boutiques for Black Friday and Cyber Monday 2026, with one page per designer people search for, for example /black-friday/canada-goose.
• Gift guides: gifts that come in one size, so nobody guesses a size: for him, for her and by budget, for example /gifts/for-him and /gifts/under-200.
• Where it was made: pieces whose own listings say where they were made, by country: /made-in/canada, /made-in/italy, /made-in/japan and /made-in/portugal.
• Colours: one page per colour and item people search, every piece of it at every boutique, for example /white-sneakers, /black-hoodies and /black-bags, and one designer's pieces in one colour, for example /black-jordans.
• Everything else: art, books, candles and objects for the home.
• Free tools: every tool on one page, each free, in the browser, with no download.
• Sizes: size charts and a converter for rings, shoes, clothes, suits, belts and hats, and one chart per designer, each with its source and the day it was read.
• Duty: what a piece costs at the door in the US, Canada, the UK or Australia, each line with its official source.
• Is it legit: whether a shop or a resale site is legit, read from its own policy pages with the day they were read: returns, duty and what it checks.
• How to spot a fake: how to check a piece before you pay, starting with who sold it, from the maker's own words.
• Sizing notes: whether a designer runs big or small, model by model, from its own size pages.
• Why it costs what it does: why a designer's pieces cost what they do, with the prices on the shelves.
• The boutiques: one note per boutique: its street, its hours, what it holds and how it sells.
• Shopping streets and cities: the shops on a street or in a neighbourhood, with addresses and hours.
• What to wear: what to wear to an event or a city, from the dress code it prints and the weather on the day.

Boutiques

Your register is the listing. When your shop is on within, your shelf is readable from any assistant or app that connects, with your name on every piece. Invite your boutique.

Common questions

Is the within MCP server free?

Yes. There is no account, no key and no charge. The only limit is the rate: a burst of 60 requests from one address, then one a second.

What is a remote MCP server?

It is an MCP server you reach at a web address instead of one you install. You give your assistant or app the address, https://shopwithin.co/mcp, and it can call the tools. Nothing runs on your own computer.

Can an agent buy a piece for me?

No. The tools only read. Every answer carries the piece's page on shopwithin.co, and you buy there, through the boutique's own checkout.

Is this agentic commerce?

It is the finding half. An agent can search the shelves, check a size and hand you the page to buy. The paying stays between you and the boutique.

How fresh are the sizes and prices?

Each piece carries stock_checked_at, the time within last read the boutique's register. Stock moves by the hour, so the product page, read fresh when you open it, is the final word.

Which cities does it cover?

The boutiques on within today are in Iwuy, Londrina and Toronto. A search for another city says so and names the cities that have boutiques. Boutiques anywhere can join by invitation.

Does it keep the photos I send?

No. visual_search matches the photograph in memory and drops it. Nothing is saved.

Do I need to sign in or share my details?

No. The server never asks for a name, an email or a login, and it cannot see anyone's saves, bag or orders.