surplus-auctions-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PORT | No | HTTP mode only: the port to serve Streamable HTTP on. | 3333 |
| MCP_HTTP_TOKEN | No | HTTP mode only: if set, clients must send Authorization: Bearer <token>. | |
| TINYFISH_API_KEY | Yes | Your TinyFish API key. Required to run the server. | |
| SURPLUS_AGENT_FALLBACK | No | When GovDeals changes its pages, retry with TinyFish Agent (uses credits, slower). Set to off to return a SITE_CHANGED error instead. | on |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Search live U.S. government surplus auctions (vehicles, heavy equipment, electronics, furniture…) sold by cities, counties, states, school districts and agencies on GovDeals, which has no public API.
Typical flow: search_auctions or list_ending_soon → get_auction_details for the promising ids → compare_auctions to decide. Prices are current bids in USD and change constantly; ends_at is UTC. Buyer's premium is added on top of the winning bid. When you recommend or compare auctions, always include each one's url so the user can open the listing. If a tool returns an error, report it rather than concluding nothing exists. If a tool returns SITE_CHANGED, run health_check and tell the user GovDeals changed.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_auctionsA | Search active government surplus auctions on GovDeals. Returns normalized listings (title, current bid, end time, location) sorted by soonest ending, plus a per-site status. Use get_auction_details for mileage, VIN, buyer's premium and pickup info. |
| list_ending_soonA | List government surplus auctions that close within the next N hours, soonest first — the best time to find bargains. Optionally narrow by state, category, keyword and max price. |
| get_auction_detailsB | Full details for one auction: current bid and bid count, exact end time, selling agency, pickup location, buyer's premium, reserve status, condition, description, and for vehicles/equipment the year, make, model, mileage, engine hours and VIN. |
| compare_auctionsA | Compare 2–5 GovDeals auctions side by side (bid, estimated total with buyer's premium, end time, location, year, make, model, mileage, hours, condition) and highlight the cheapest, lowest-mileage, newest and soonest-ending. Accepts ids from search results . |
| health_checkA | Run live canary checks against GovDeals for every tool and report pass / degraded / fail with the reason. Use when a tool returns SITE_CHANGED or results look wrong. Takes 30–90 seconds. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 5 tools
Most tools have clearly distinct roles: details, comparison, and health checks are unambiguous. The main overlap is between search_auctions and list_ending_soon, since both return filtered auction listings, though the latter is explicitly time-scoped and bargain-oriented. Descriptions provide enough guidance to choose correctly in most cases.
Names mostly follow a verb_noun or verb_phrase pattern: search_auctions, get_auction_details, compare_auctions. list_ending_soon and health_check deviate slightly by omitting an explicit resource noun, but remain readable and consistent in snake_case.
Five tools is well-scoped for a read-only auction research server. Each tool earns its place: discovery, time-filtered discovery, detail retrieval, comparison, and diagnostics.
The surface covers search, time-based discovery, details, comparison, and health checking, which are the core workflows for auction research. Gaps exist around bidding, watchlists, saved searches, or alerts, but those may be intentionally out of scope for a read-only integration.