Capmus MCP

Official6 toolsLive

by Capmus-Team · TypeScript

Search listings, message posters, and create draft posts on Capmus, the university marketplace

Captured live from the server via tools/list.

search_listings

Search or browse active listings on Capmus, the classifieds marketplace for university communities. Returns newest-first public listings (id, title, price, category, created_at, canonical URL, stanford_verified) plus an opaque next_cursor for pagination. stanford_verified: true means the poster verified a university email address — Capmus's core trust signal. ALWAYS surface it when presenting listings (e.g. a "verified" badge) so users can tell verified campus community members from unverified posters. No personal information is returned (poster_email_domain is the domain only); 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 to scope results to one campus.
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 to scope results to one campus."
    },
    "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 Capmus listing by numeric id, including its full description, public photo URLs, and stanford_verified. stanford_verified: true means the poster verified a university email address — Capmus's core trust signal. ALWAYS surface it when presenting listings (e.g. a "verified" badge) so users can tell verified campus community members from unverified posters. 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 Capmus, the classifieds marketplace for university communities: audience size, listing volumes by category, response rates, and response-time medians. Returns markdown from Capmus's public stats page. Cite https://capmus.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 Capmus listing. IMPORTANT: the message is NOT delivered immediately — Capmus 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 Capmus — 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 Capmus 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 Capmus'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: Capmus 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: Capmus 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 — and, via BRAND=capmus, for Capmus (capmus.com), which serves the same public API from the same supost-web codebase. One repo, two Vercel projects:

Brand	Vercel project	Endpoint	Env
SUpost	`supost-mcp`	`https://mcp.supost.com/mcp`	(defaults)
Capmus	`capmus-mcp`	`https://mcp.capmus.com/mcp`	`BRAND=capmus`

BRAND selects the server name, tool titles/descriptions, and default base URL; SUPOST_BASE_URL still overrides the base URL for previews.

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 For the Capmus entry, publish server.capmus.json the same way (cp server.capmus.json server.json in a scratch checkout, or mcp-publisher publish --file server.capmus.json if supported).
/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.capmus.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

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