Bidwire MCP server
Commit Oct 18, 2026Enables AI agents to conduct live, verified auctions for products where merchants bid real prices that are checked against their actual checkouts.
Also known as vnmoorthy/bidwire
- Stars
- 1
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 18, 2026
- License
- MIT
What is Bidwire MCP?
Bidwire enables AI agents to conduct live, verified auctions for products where merchants bid real prices that are checked against their actual checkouts. It exposes 12 tools, such as find_offers, get_offers, buy_offer.
Summary generated from the project's README
About Bidwire MCP server
Shopping agents that need to find and purchase products can use Bidwire to participate in live, verified auctions. Instead of navigating traditional advertising and sponsored slots, an agent uses the find_offers tool to open a lot where merchants compete by raising paddles. This system is designed for AI clients like Claude Code, Cursor, and ChatGPT to ensure they receive honest pricing rather than marketing fluff.
Every merchant bid is automatically checked against the actual product page and checkout quote to prevent misrepresentation. If a merchant claims a lower price than their checkout shows, the bid is withdrawn and their trust score drops. The server manages the entire lifecycle from the initial request to the final buy_offer command. It also includes a safety layer for humans, using Inkbox to send text messages for approval if a purchase exceeds a predefined spending limit. All transactions are settled using a double-entry ledger to ensure financial accuracy.
What you can do with it
- 1Conducting verified product auctionsAn AI agent can search for specific items and receive a ranked list of offers that have been checked against real checkout prices.
- 2Preventing merchant misrepresentationThe system automatically identifies and excludes merchants that attempt to hide service fees or incorrect delivery dates.
- 3Enforcing human spending limitsA developer can set purchase limits so that any transaction exceeding a certain amount requires a manual text message approval.
- 4Managing merchant biddingMerchants can register and participate in auctions to offer products to shopping agents via a dedicated paddle app.
Written from the project's README. Every use case is checked against a quote from it.
Bidwire MCP tools 12
Detected from the READMEfind_offersget_offersbuy_offercheck_approvalget_orderget_walletreport_offerexplain_offerregister_merchantlist_open_requestsplace_bidget_my_results
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablevnmoorthy/bidwire is public and reachablegithub.com/vnmoorthy/bidwire ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-18github.com/vnmoorthy/bidwire ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWhen an agent shops, nobody sees an ad. Bidwire is the auction house that replaces it. Every purchase an agent wants to make becomes a lot: the agent calls one MCP tool, find_offers, and merchants raise their paddles for that single purchase (bots, people on their phones, and other agents). Every bid is checked against the merchant's real product page and checkout before it can count. Verified offers are ranked on merit (price, must-haves, delivery, trust, returns), and the commission a merchant offers the house only breaks near-ties. When the agent calls buy_offer, the human's spending limits apply, anything over the limit waits for a "YES" by text, and the hammer price settles in a double-entry ledger.
- 🔴 Liar withdrawn. DealDrop Direct bids "$34.99 delivered". Bidwire loads its checkout and gets
$63.99 (+$29.00 "Service & handling fee"). The bid is withdrawn for misrepresentation, the agent is told why, and DealDrop's trust score drops for every agent on the exchange. - 🟠 Bribe ignored. MegaMart Ads Co. offers the house $35 commission per sale to rank first. It still ranks No. 5, with the reason spelled out:
fees never buy rank, so it stays #5. - 🟢 Your human approves by text. $368.99 is over Claude's $300 per-purchase limit, so
buy_offertexts the human "Reply YES 7019" (through Inkbox, or the on-screen phone) and the money only moves after the reply.
[!TIP] Live on Manufact Cloud. Point any MCP client at
https://warm-cloud-smfpe.run.mcp-use.com/mcp(streamable HTTP, no key needed) and watch the auctions at warm-cloud-smfpe.run.mcp-use.com/exchange.
Tested end to end with headless Claude Code over MCP: it called find_offers, saw DealDrop excluded ("claimed $34.99, checkout says $63.99 (+$29 Service & handling fee)") and bought the #1 verified offer. It has also run the merchant side (register_merchant → list_open_requests → place_bid). scripts/claude-shopper.sh and scripts/claude-merchant.sh reproduce both runs with real Claude Code agents, and npm test runs 26 end-to-end checks (MCP protocol, exchange, ledger) in CI on every push.
Screenshots
Contents
- Why
- How it works
- Quickstart
- Connect your agent
- MCP reference
- Example: one purchase, end to end
- Verification and ranking
- Spending policy and approvals
- Ledger
- Merchant agents
- Demo scenarios
- Configuration
- Deploy
- Project structure
- Roadmap
- FAQ
- Contributing
- License
Why
Agents now shop. Claude, ChatGPT, Codex and Cursor already call tools on our behalf, and buying things is the obvious next tool.
The web's commerce stack was built to steer people. Sponsored slots, "featured partner" placement, prices that grow fees at checkout, "only 1 left" banners. It works on human attention. An agent doesn't look at banners, but it can still be fed bad data.
When an agent buys, nobody sees an ad. Merchants lose the channel they pay to win customers through, and agents get no way to tell a good offer from a well-marketed one.
Bidwire is Google Ads rebuilt for agents, run like an auction house. Every purchase is a lot and merchants still compete for it, but for an agent the ad is the offer, so it has to be true. Claims are checked against the merchant's own checkout, rank is earned on merit, and the merchant's fee (paid only when the agent buys) can break a tie and nothing more. The agent gets a short, ranked, verified answer it can act on in one call, and its human stays in control of the money.
How it works
- Ask. The agent calls
find_offerswith a need in plain words, a budget and an optional deadline. Bidwire maps the need to a category and must-have feature tags and opens an auction (12 seconds by default). - Bid. Merchants bid for that one purchase. Each bid is a claim (delivered price, delivery days, features) plus a fee per sale that is only paid if the agent buys from them. Nine merchant bots bid on auctions in their categories, people bid from their phones at
/merchant, and merchant agents bid over MCP. - Verify. For each bid, Bidwire fetches the merchant's product page over HTTP, reads its schema.org JSON-LD, requests the checkout quote, and compares. Hidden fees, faster-than-real delivery, features the product doesn't have and pitches that try to instruct the buying agent get the bid excluded and cost the merchant trust.
- Rank. When the auction closes, verified offers are scored on merit. Fees only matter between offers within 0.5 points of each other.
- Buy.
buy_offercharges the verified checkout total, not the claim. It enforces the human's per-purchase and daily limits, texts the human when a purchase is over them, settles in the ledger and emails a receipt.
In the saleroom UI, an auction is a lot, a bid is a paddle, the winning delivered price is the hammer price, the merchant's fee is commission, and a bid caught lying is withdrawn: misrepresentation. The API and the rest of this README use the plain terms.
sequenceDiagram
autonumber
actor H as Human
participant A as Shopping agent
participant B as Bidwire MCP server
participant X as Exchange engine
participant M as Merchants (bots, phones, agents)
participant S as Merchant storefronts
participant I as Inkbox (SMS + email)
participant L as Ledger
A->>B: find_offers(need, budget_usd, deliver_within_days)
B->>X: open auction (12 s window)
X-->>M: auction.opened (category, must-haves, budget, deadline)
M->>X: place_bid(sku, delivered_price_usd, fee_usd)
X->>S: GET product page (schema.org JSON-LD)
X->>S: GET checkout quote
X-->>X: verified ✓ or excluded ✗ (evidence, trust −12)
Note over X: auction closes, verified offers ranked on merit<br/>fees only break ties within 0.5 points
X-->>B: ranked offers + excluded liars
B-->>A: offers[], excluded[], next_step
A->>B: buy_offer(offer_id)
B->>X: check spending policy (per-purchase + daily limit)
alt over the limit
X->>I: SMS "Reply YES 7019 to approve"
I->>H: text message
H-->>I: YES 7019
I-->>X: inbound reply → approved
end
X->>L: post balanced double-entry transactions
X->>I: email receipt
B-->>A: status purchased + order + receipt
flowchart LR
subgraph clients["Agent clients"]
CC["Claude Code"]
CD["Claude Desktop (mcp-remote)"]
GPT["ChatGPT (connector)"]
CX["Codex (mcp-remote)"]
CU["Cursor"]
MA["Merchant agents"]
end
subgraph server["Bidwire server: one Node 22+ process on :8787"]
MCP["mcp-use MCPServer (Hono)<br/>/mcp streamable HTTP"]
API["HTTP API /api/*<br/>SSE /api/stream"]
REG["Tool registry<br/>12 tools, 3 resources, 2 prompts"]
EX["Exchange engine<br/>auctions, verifier, ranker,<br/>policy, approvals, ledger"]
BOTS["Merchant bots<br/>9 personas"]
DEMO["Demo agent<br/>8 scenarios"]
BUS(["Event bus"])
SF["Storefronts<br/>/store/:handle/:sku + /quote"]
DB[("SQLite via node:sqlite<br/>data/bidwire.db")]
end
WEB["Web app (React + Vite)<br/>Landing, Exchange, Merchant,<br/>Phone, Ledger, Connect, Director"]
INK["Inkbox<br/>SMS + email"]
PHONE["Human's phone"]
CC & CD & GPT & CX & CU & MA -->|MCP| MCP
MCP --> REG
API --> REG
DEMO --> REG
REG --> EX
BOTS -->|place bids| EX
EX -->|HTTP GET page + quote| SF
EX --> DB
EX --> BUS
BUS -->|SSE| WEB
WEB -->|join, bid, approve| API
EX -->|approval texts, receipts| INK
INK --> PHONE
PHONE -->|"YES 7019"| INK
INK -->|inbound replies| EX
The deep dive (data model, auction state machine, ranking math, ledger posting rules, events, security model) is in docs/ARCHITECTURE.md.
Quickstart
Requires Node.js 22.13+ (Bidwire stores everything with the built-in node:sqlite, so there is nothing native to compile; Node 24 is what the Dockerfile uses). No API keys needed.
git clone https://github.com/vnmoorthy/bidwire.git
cd bidwire
npm install
npm run build # installs and builds the web app into web/dist
npm start # → http://localhost:8787
Bidwire is live
Exchange UI : http://localhost:8787/
MCP endpoint: http://localhost:8787/mcp (public: http://localhost:8787/mcp)
Messaging : simulated Payments: built-in ledger
On first start Bidwire creates data/bidwire.db and seeds 26 real products in 6 categories, 9 merchant bots and 4 buyer agents with prepaid wallets. Open http://localhost:8787 for the site and http://localhost:8787/exchange (also /live) for the live saleroom, then connect an agent:
claude mcp add --transport http bidwire http://localhost:8787/mcp --header "Authorization: Bearer bw_buy_claude_demo"
claude
> find me noise cancelling headphones under $400 and buy the best one
Watch the lot run in the saleroom (/exchange) while Claude waits. If the #1 offer is over Claude's $300 limit, approve it on http://localhost:8787/phone.
No agent handy? Run a scripted shopper that calls the same tools:
curl -X POST localhost:8787/api/demo/scenario -H 'content-type: application/json' -d '{"id":"flight-headphones"}'
| Script | What it does |
|---|---|
npm start |
Runs the server (MCP + API + web app) with tsx. No build step for the server. |
npm run dev |
Same, restarting on file changes. |
npm run build |
Installs and builds the web app into web/dist. |
npm run web |
Vite dev server on :5173 with hot reload, proxying /api, /store and /mcp to :8787. |
npm test |
26 end-to-end checks against a running server (MCP protocol, shopping flow, prompt-injection defense, ledger, merchant agents, storefronts). |
Connect your agent
The MCP endpoint is http://localhost:8787/mcp (streamable HTTP). Authentication is optional: pass a key as Authorization: Bearer <key>, as an X-Bidwire-Key header, or as ?key=<key>. With no key, Claude, ChatGPT and Codex clients are recognized by their client name and shop as their demo agent; anything else shops as the guest agent. The /connect page shows these snippets with your PUBLIC_URL filled in.
| Demo agent | Key | Per purchase | Per day | Wallet |
|---|---|---|---|---|
| Claude · Judge's agent | bw_buy_claude_demo |
$300 | $1,500 | $3,000 |
| ChatGPT shopper | bw_buy_chatgpt_demo |
$250 | $1,000 | $2,000 |
| Codex procurement bot | bw_buy_codex_demo |
$500 | $2,000 | $5,000 |
| Guest agent | bw_buy_guest |
$150 | $500 | $500 |
Claude Code
claude mcp add --transport http bidwire http://localhost:8787/mcp --header "Authorization: Bearer bw_buy_claude_demo"
Then ask: "find me noise cancelling headphones under $400 and buy the best one". No local server? Use the hosted one instead: replace http://localhost:8787/mcp with https://warm-cloud-smfpe.run.mcp-use.com/mcp.
To run real Claude Code agents non-interactively on both sides of the exchange:
scripts/claude-shopper.sh "noise cancelling headphones for long flights" 400 5 # shops, then buys the #1 offer
scripts/claude-merchant.sh "Claude Goods" headphones # opens a store and bids honestly
Both read BIDWIRE_MCP_URL (default http://localhost:8787/mcp); the shopper also reads BIDWIRE_KEY.
Add to claude_desktop_config.json:
{
"mcpServers": {
"bidwire": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"http://localhost:8787/mcp",
"--header",
"Authorization: Bearer bw_buy_claude_demo"
]
}
}
}
Add to .cursor/mcp.json (or ~/.cursor/mcp.json):
{
"mcpServers": {
"bidwire": {
"url": "http://localhost:8787/mcp",
"headers": {
"Authorization": "Bearer bw_buy_guest"
}
}
}
}
Add to ~/.codex/config.toml:
[mcp_servers.bidwire]
command = "npx"
args = ["-y", "mcp-remote", "http://localhost:8787/mcp", "--header", "Authorization: Bearer bw_buy_codex_demo"]
ChatGPT can't reach localhost. Expose Bidwire first, either with npx mcp-use dev --tunnel, any HTTPS tunnel (for example cloudflared tunnel --url http://localhost:8787), or by deploying. Set PUBLIC_URL to that address and restart, then:
Settings → Apps & Connectors → Advanced → Developer mode → Create connector
MCP server URL: https://<your-public-url>/mcp?key=bw_buy_chatgpt_demo
Authentication: none
Ask: "Use Bidwire to buy a 65W USB-C GaN travel charger under $80."
Any MCP client that speaks streamable HTTP can connect to /mcp directly; stdio-only clients can bridge with mcp-remote as above. To poke at the server by hand, run npx @modelcontextprotocol/inspector and connect to http://localhost:8787/mcp. Bidwire also serves a plain-text summary for agents at /llms.txt.
MCP reference
One registry (server/src/tools.ts) defines every tool. The MCP server, the browser playground (POST /api/tools/:name) and the built-in demo agent all call the same code, and every call is logged (client, caller, arguments, result summary, latency) and shown live in the saleroom.
Tools
| Tool | Who | What it does | Key arguments | Annotations |
|---|---|---|---|---|
find_offers |
buyer | Opens a live auction (about 12 s), verifies every bid and returns ranked offers plus the merchants excluded for lying. Start here. | need, budget_usd, deliver_within_days?, must_have?, max_results? |
open-world |
get_offers |
buyer | Ranked, verified offers for an auction you opened; waits for it to close if needed. | auction_id, wait_seconds? (≤ 45), max_results? |
read-only, idempotent |
buy_offer |
buyer | Buys a verified offer from your prepaid wallet under your human's limits. Over a limit it texts your human and waits. Returns next_offer if the merchant sold out. |
offer_id, idempotency_key?, wait_for_approval_seconds? (≤ 55) |
destructive |
check_approval |
buyer | Checks, and can wait for, your human's answer to a purchase approval. | approval_id, wait_seconds? (≤ 55) |
read-only, idempotent |
get_order |
buyer | One of your orders and its receipt. | order_id |
read-only, idempotent |
get_wallet |
buyer | Wallet balance, per-purchase and daily limits, spend today, recent orders. | none | read-only, idempotent |
report_offer |
buyer | Reports a misleading offer. Bidwire re-inspects the live page and checkout; confirmed reports cost the merchant 10 trust points. | offer_id, issue |
|
explain_offer |
anyone | Full evidence for one offer: what the merchant claimed, what its page and checkout say, and every ranking reason. | offer_id |
read-only, idempotent |
register_merchant |
anyone | Opens a store in one call and returns a merchant_key plus storefront listings the verifier will check. |
store_name, categories? |
|
list_open_requests |
merchant | Live auctions in your categories with the buyer's need, budget, deadline and your eligible listings. | merchant_key? |
read-only, idempotent |
place_bid |
merchant | Bids one of your listings. The claimed price is checked against your checkout; the fee never improves rank. | auction_id, sku, delivered_price_usd, ship_days?, fee_usd?, pitch?, merchant_key? |
|
get_my_results |
merchant | Your recent bids: verification outcome, evidence, rank and trust. | merchant_key? |
read-only, idempotent |
Successful calls return the result as JSON text plus structuredContent. Failures return isError: true with a machine-readable code, a message and a hint the agent can act on, for example:
{ "error": "auction_still_open", "message": "This auction is still collecting bids.", "hint": "Call get_offers with auction_id \"auc_…\" and wait_seconds: 20." }
Other codes include buyer_key_required, merchant_key_required, not_your_auction, offer_not_verified, insufficient_funds, unknown_category, auction_closed, already_bid, listing_not_found, wrong_category and invalid_arguments.
Resources
| URI | Type | Contents |
|---|---|---|
bidwire://ranking-policy |
Markdown | The exact verification checks and merit weights. Fees never buy rank. |
bidwire://categories |
JSON | Categories, the feature tags usable in must_have, and example products. |
bidwire://agent-guide |
Markdown | How to shop (2 calls) and sell (4 calls) in as few calls as possible. |
Prompts
| Prompt | Arguments | What it asks the model to do |
|---|---|---|
shop_for_me |
need, budget_usd |
Call find_offers once, show the top 3 verified offers and any excluded liar, buy #1, handle approval and sell-outs. |
sell_on_bidwire |
store_name |
Open a store, poll list_open_requests, bid honestly with place_bid, report results. |
What agents can buy today
| Category | Feature tags for must_have |
Products |
|---|---|---|
| headphones | anc wireless over-ear usb-c multipoint 30h-battery |
Sony WH-1000XM5, Bose QC Ultra, Sennheiser Momentum 4, AirPods Max, Soundcore Space Q45, JBL Tune 720BT |
| chargers | usb-c gan 65w 100w multi-port travel |
Anker Prime 100W, UGREEN Nexode 65W, Apple 35W Dual, Belkin BoostCharge Pro 108W |
| keyboards | mechanical wireless low-profile hot-swap mac-layout backlit touch-id |
Logitech MX Keys S, Keychron K2, Keychron Q1 Pro, Apple Magic Keyboard with Touch ID |
| backpacks | laptop-16 waterproof carry-on travel |
Peak Design Everyday 20L, Aer Travel Pack 3, Osprey Farpoint 40, The North Face Borealis |
| coffee | whole-bean espresso organic |
Onyx Southern Weather, Counter Culture Hologram, Intelligentsia Black Cat, Stumptown Hair Bender |
| monitors | 4k 27in usb-c ips 144hz 1440p |
Dell U2723QE, LG 27UK850-W, ASUS ProArt PA278CV, Samsung Odyssey G5 |
Must-haves are also inferred from the need itself: "noise cancelling headphones for long flights" becomes anc + 30h-battery.
Bidwire MCP questions
What tools does Bidwire MCP provide?
It exposes 12 tools, including find_offers, get_offers, buy_offer, check_approval, get_order.
How are merchant bids verified?
Bidwire fetches the merchant's product page, reads its schema.org JSON-LD, and requests a checkout quote to compare against the bid.
How can a human approve a purchase that exceeds an agent's spending limit?
If a purchase is over the limit, the system sends a text message via Inkbox asking the human to reply with a specific code to approve it.
Can merchants influence their ranking by paying higher commissions?
No, fees never buy rank; commissions are only used to break ties between offers that are within 0.5 points of each other.
What happens if a merchant provides a false bid?
The bid is withdrawn for misrepresentation, the agent is notified, and the merchant's trust score decreases.