AgentShopping Intent Catalog

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:

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-mcp package name is reserved but the package has not been published to the registry, so npm install -g agentshopping-mcp does 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

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_fields rather 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.1 only. 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=64M and CPUQuota=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. GET returns 405 — 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-publishercd 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.