agentshopping-mcp
An MCP server that exposes the AgentShopping buyer-intent catalog to any MCP-compatible agent.
It is read-only. It holds no funds, places no orders, and writes nothing. It returns dated, sourced facts — and states plainly what it does not know.
Two ways to use it
1. Remote endpoint (recommended, zero install)
https://agentshopping.org/mcp
MCP Streamable HTTP. Point any MCP client at the URL:
{
"mcpServers": {
"agentshopping": {
"url": "https://agentshopping.org/mcp"
}
}
}
This endpoint is listed in the official MCP Registry:
| Field | Value |
|---|---|
| Name | org.agentshopping/intent-catalog |
| Version | 0.1.1 |
| Namespace | domain reverse-DNS of agentshopping.org (HTTP authentication) |
| Status | active |
| Published | 2026-11-08T13:47:55Z |
| Source | https://github.com/wken2238-byte/agentshopping-mcp |
Verify it yourself:
curl 'https://registry.modelcontextprotocol.io/v0.1/servers?search=agentshopping'
2. Local stdio server (runs on your machine)
node src/index.js
{
"mcpServers": {
"agentshopping": {
"command": "node",
"args": ["/absolute/path/to/agentshopping-mcp/src/index.js"]
}
}
}
Not on npm yet. The
agentshopping-mcppackage name is reserved but the package has not been published to the registry, sonpm install -g agentshopping-mcpdoes not work yet. Until it does, run it from a checkout as shown above.
Pointing it at a different catalog
The stdio server reads AGENTSHOPPING_API_BASE if set, and falls back to https://agentshopping.org. Use it to run against a self-hosted or mirrored catalog:
{
"mcpServers": {
"agentshopping": {
"command": "node",
"args": ["/path/to/agentshopping-mcp/src/index.js"],
"env": { "AGENTSHOPPING_API_BASE": "https://your-mirror.example" }
}
}
}
The tools
| Tool | Returns |
|---|---|
list_intents | 100 buyer transaction intents with supply status |
get_intent | One intent's required context, decision factors, honest supply status |
list_offers | Supply catalog with dated verified facts and explicit unverified fields |
match_workload | Deterministic, explainable match or rejection for a workload |
match_workload returns matches and rejections with reasons. It does not rank, score, or declare a "best" option — a rejection is a first-class answer, not a failure.
Honest limitations
- 99 of 100 intents have no verified supply partner. Every response says so explicitly.
- No prices, specifications, vendors, or availability are asserted. Unknown fields are listed under
unverified_fieldsrather than guessed. - Intent ordering is editorial, not measured demand.
- One supply partner exists today. This is a protocol skeleton, not a marketplace.
- Outbound provider links require an informed human click. No auto-redirect, no iframe.
- The registry listing does not mean anyone is using it. It means it can be found.
Running the remote endpoint yourself
The deployed endpoint is src/http-server.py — Python 3 standard library only, no dependencies:
MCP_PORT=8787 MCP_DATA_ROOT=/path/to/site python3 src/http-server.py
Design constraints it holds to:
- Binds to
127.0.0.1only. Publish it behind a TLS reverse proxy. - Reads static JSON from disk. No outbound network calls, no polling, no background work.
- Request body capped at 64 KB; path allowlist with traversal protection.
- Threaded with a concurrency cap and a per-connection timeout, so one slow client cannot block the others.
- Runs under systemd with
MemoryMax=64MandCPUQuota=10%.
src/http-server.cjs is the same server in Node, kept for reference. The deployed instance is the Python one.
Protocol details
- Remote: MCP Streamable HTTP over
POST /mcp.GETreturns405— no SSE stream is held open. - Local: newline-delimited JSON-RPC over stdin/stdout (MCP stdio transport). Logs go to stderr only. Requires Node.js >= 18.
- Supported methods:
initialize,ping,tools/list,tools/call,resources/list(empty),prompts/list(empty). Notifications are ignored without a response.
Manual test
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
'{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_intent","arguments":{"id":"book-flight"}}}' \
| node src/index.js
Publishing a change to the registry
npm i -g mcp-publisher
cd agentshopping-mcp
./publish.sh 0.1.1 # bumps the version in server.json, then publishes
publish.sh authenticates with HTTP authentication — it signs a challenge with a local ECDSA P-384 key and the registry fetches the public key from https://agentshopping.org/.well-known/mcp-registry-auth. Nothing human needs to click anything.
Note the registry's own JWT lives for only 5 minutes, so the login and publish steps are chained with no gap between them. The script handles that, plus a retry for the occasional network stall.
The full walkthrough, including how the proof file and key pair are produced, is in 发布指引.md (Chinese).
License
MIT — see LICENSE.