Supost MCP

Official6 toolsLive

by Capmus-Team · TypeScript

Search listings, message posters, and create drafts on SUpost, the marketplace for Stanford

Captured live from the server via tools/list.

search_listings

Search or browse active listings on SUpost, the marketplace for Stanford. Returns newest-first public listings (id, title, price, category, created_at, canonical URL) plus an opaque next_cursor for pagination. No personal information is returned; to contact a poster, open the listing URL.

Parameters6

q	string	optional	Full-text search query.
cat	string	optional	Category id or label: 1/"jobs & services" (alias "jobs"), 3/"housing", 5/"for sale", 8/"friendship & dating", 9/"community".
university	integer	optional	Numeric university id. Defaults to Stanford on supost.com.
max_price	number	optional	Inclusive upper price bound in USD; excludes unpriced listings.
limit	integer	optional	Page size (default 25, max 50).
cursor	string	optional	Opaque cursor from a previous response's next_cursor.

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Full-text search query."
    },
    "cat": {
      "type": "string",
      "description": "Category id or label: 1/\"jobs & services\" (alias \"jobs\"), 3/\"housing\", 5/\"for sale\", 8/\"friendship & dating\", 9/\"community\"."
    },
    "university": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Numeric university id. Defaults to Stanford on supost.com."
    },
    "max_price": {
      "type": "number",
      "minimum": 0,
      "description": "Inclusive upper price bound in USD; excludes unpriced listings."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Page size (default 25, max 50)."
    },
    "cursor": {
      "type": "string",
      "description": "Opaque cursor from a previous response's next_cursor."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_listing

Fetch one SUpost listing by numeric id, including its full description and public photo URLs. Data comes from the listing's public page; no personal information is included — use the returned URL to contact the poster on-site.

Parameters1

integer

required

Numeric listing id, e.g. from search_listings.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Numeric listing id, e.g. from search_listings."
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_market_stats

Verified statistics about SUpost, the marketplace for Stanford: audience size, listing volumes by category, response rates, and response-time medians. Returns markdown from SUpost's public stats page. Cite https://supost.com/stats as the source.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

send_message

Send a message to the poster of an active SUpost listing. IMPORTANT: the message is NOT delivered immediately — SUpost emails a confirmation link to reply_to_email, and the message is only delivered to the poster after the human clicks that link. Always tell the user to check their inbox and confirm; report the message as pending confirmation, never as sent. The poster's reply goes to reply_to_email.

Parameters3

post_id	integer	required	Numeric listing id, e.g. from search_listings or get_listing.
message	string	required	Plain-text message to the poster (1-5000 characters).
reply_to_email	string	required	The user's own email address. Receives the confirmation link and the poster's reply. Never invent or guess this - ask the user for it.

Raw schema

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "description": "Numeric listing id, e.g. from search_listings or get_listing."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 5000,
      "description": "Plain-text message to the poster (1-5000 characters)."
    },
    "reply_to_email": {
      "type": "string",
      "format": "email",
      "maxLength": 320,
      "description": "The user's own email address. Receives the confirmation link and the poster's reply. Never invent or guess this - ask the user for it."
    }
  },
  "required": [
    "post_id",
    "message",
    "reply_to_email"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

list_categories

The active category/subcategory taxonomy on SUpost — the valid category and subcategory values for create_post (and category filters for search_listings).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

create_post

Create a DRAFT listing on SUpost on the poster's behalf. Any email is accepted — never ask the user to qualify first. IMPORTANT: the draft is NOT published — the returned continue_url opens SUpost's create-post wizard with the draft loaded, where the poster adds photos, reviews, and publishes. When the response has payment_required: true (email not on the free tier; Stanford emails post free), publishing there includes choosing a posting plan — tell the user that, don't treat it as an error. Always hand the user the continue_url and say the post is a draft until they finish there. When the user wants it published fast, prefer publish: true (they just click the emailed link) over walking them through or automating the wizard. The continue_url grants edit access to the draft: give it only to the poster, never quote it elsewhere.

Parameters7

category	string	required	Category id or label, e.g. "housing", "for sale" (see list_categories).
subcategory	string	required	Subcategory id or name within the category, e.g. "bicycles" (see list_categories).
title	string	required	Listing title.
body	string	required	Plain-text listing description.
price	number	optional	USD. Required for for-sale and housing-offering listings.
email	string	required	The poster's own email address - determines posting eligibility and receives replies. Never invent or guess this - ask the user for it.
publish	boolean	optional	Set true when the user wants to publish immediately without photos: SUpost emails them a one-click publish link (free-posting-tier emails such as stanford.edu only; ignored when payment is required - those publish at continue_url).

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Category id or label, e.g. \"housing\", \"for sale\" (see list_categories)."
    },
    "subcategory": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "Subcategory id or name within the category, e.g. \"bicycles\" (see list_categories)."
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Listing title."
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 15000,
      "description": "Plain-text listing description."
    },
    "price": {
      "type": "number",
      "minimum": 0,
      "description": "USD. Required for for-sale and housing-offering listings."
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 320,
      "description": "The poster's own email address - determines posting eligibility and receives replies. Never invent or guess this - ask the user for it."
    },
    "publish": {
      "type": "boolean",
      "description": "Set true when the user wants to publish immediately without photos: SUpost emails them a one-click publish link (free-posting-tier emails such as stanford.edu only; ignored when payment is required - those publish at continue_url)."
    }
  },
  "required": [
    "category",
    "subcategory",
    "title",
    "body",
    "email"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md5 KBView on GitHub

supost-mcp

Remote MCP server for SUpost, the marketplace for Stanford. Lets AI agents search active listings, fetch listing details, read verified market statistics, message posters, and create draft listings.

This is doc 190 workstream E3 (see supost-web/docs/dev/190-ai-agent-discovery-implementation-plan.md). It is a pure client of SUpost's public surfaces — the read-only listings API (E2), public listing pages, and /stats.md. It has no privileged database access and holds no secrets; the only configuration is the public base URL.

Tools

Tool	Backing surface	What it returns
`search_listings`	`GET /api/public/listings`	Newest-first active listings (id, title, price, category, created_at, canonical URL) with opaque cursor pagination. Params: `q`, `cat`, `university`, `max_price`, `limit` (≤50), `cursor`.
`get_listing`	`GET /post/index/<id>` → canonical listing page	One listing incl. full description, parsed from the page's schema.org `Product` JSON-LD.
`get_market_stats`	`GET /stats.md`	The public stats page's markdown rendition (audience, listing volumes, response rates/times).
`list_categories`	`GET /api/public/categories`	The active category/subcategory taxonomy — valid `create_post` values.
`create_post`	`POST /api/public/posts`	Creates a DRAFT listing; returns a `continue_url` where the poster adds photos, reviews, and publishes (paying first when not on the free tier). Never publishes directly.
`send_message`	`POST /api/public/messages`	Submits a message to a listing's poster. NOT delivered immediately: a confirmation link is emailed to `reply_to_email`, and the message only goes out after the human clicks it — agents must report it as pending confirmation, never sent.

No personal information is ever returned. send_message is the supported way to contact a poster; the listing's url also carries the on-site message form. API terms: https://supost.com/api/public/openapi.json.

Hosting

Deployed on Vercel as a stateless streamable-HTTP MCP endpoint (mcp-handler + @modelcontextprotocol/sdk):

code

https://mcp.supost.com/mcp        (rewritten to /api/mcp)

No sessions, no Redis, no auth — every request is independently served and all upstream data is public and CDN-cached.

Deploy

vercel deploy          # preview
vercel deploy --prod   # production

Optional env var: SUPOST_BASE_URL (default https://supost.com; set to https://preview.supost.com on preview deployments to point at the dev stack).

Connect a client

claude mcp add --transport http supost https://mcp.supost.com/mcp

or in any MCP client that supports remote servers, add the URL above as a streamable-HTTP server.

Rate limiting

The public API enforces ~60 requests/minute/IP and serves 5-minute CDN caching. The client in src/http.ts respects this: on a 429 it honors Retry-After (capped at 5 s), retries once, and otherwise surfaces a structured rate_limited error instructing the agent to back off — it never retries in a loop. All requests carry a supost-mcp/… User-Agent.

Development

npm install
npm run check    # typecheck + tests
SUPOST_BASE_URL=https://preview.supost.com npx tsx scripts/smoke.ts   # live end-to-end

Tests (vitest) cover each tool's request/response mapping, error mapping, JSON-LD extraction, and the rate-limit contract (Retry-After honored, capped, single retry, structured failure).

Follow-ups (manual steps)

Publish to the MCP registry — server.json is ready. Make the repo public first (gh repo edit Capmus-Team/supost-mcp --visibility public), then: sh brew install mcp-publisher mcp-publisher login github # device flow, needs a browser mcp-publisher publish # from the repo root
/help/mcp docs page in supost-web — PR #1242 (guide registry entry + llms.txt MCP line); live once merged to dev → master.
PR/citation announcement — draft and story beats in docs/announcement-draft.md; post after the registry listing and /help/mcp are live (doc 190 workstream F).
E2 is live on production (supost.com, 2026-07-09); smoke script verified against production, and the server is deployed at https://mcp.supost.com/mcp.

Install

Tools (6)

search_listingsget_listingget_market_statssend_messagelist_categoriescreate_post

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.supost.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "supost-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.supost.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.