ADR-006 Accepted 2026-05-20

MCP Service for Machine Consumption

AI agents interact with madcatalog through MCP tools; the server absorbs MPP payment complexity so agents only need to provide bid details.

Context

AI agents using MCP-capable hosts (Claude Desktop, Continue, Cursor) invoke server capabilities as tool calls. The MPP 402 challenge-response flow — receiving a WWW-Authenticate: Payment header, constructing an Authorization: Payment credential, retrying, and verifying the Payment-Receipt — is complex to implement correctly in every agent.

Centralising MPP handling in the MCP server means agents across all host environments get a consistent, safe payment experience without duplicating protocol logic.

Decision

Expose an MCP server (port :8082, stdio or SSE transport) alongside the REST API. The server provides three tools: place_ad (MPP-protected), get_catalog, and get_ad.

The MCP server handles the MPP 402 challenge-response internally, surfacing payment errors as JSON-RPC error code -32042 (Payment Required) with the challenge in error.data. On successful payment the MCP client retries with the credential in _meta.credential.

MCP Inspector (npx @modelcontextprotocol/inspector, port :5173) is the local testing tool for all MCP tool calls.

Consequences

Positive
  • Agents call place_ad as a native tool call; no MPP headers to manage
  • MPP payment complexity is centralised and tested once, not duplicated across agent implementations
  • Works natively with Claude Desktop, Continue, Cursor, and any MCP-capable host
  • get_catalog returns the same data as the REST API; no dual-maintenance of catalog logic
Negative
  • Adds a second runtime process alongside SAM local; local dev stack now has two servers to manage
  • Agents without an MCP-capable host must use the REST API directly and implement MPP client-side
  • MCP is a newer standard; ecosystem tooling and SDK stability are still maturing

Alternatives Considered

OptionWhy not chosen
REST API only Agents must implement MPP client-side; acceptable for sophisticated developers but raises the integration floor for most agents
Agent SDK wrapper library (TypeScript / Python) Useful complement to MCP but requires per-language implementations; MCP is host-agnostic and already supported by Claude Desktop
WebSocket streaming Useful for real-time rank updates but not necessary for bid placement; can be added incrementally without changing the core MCP tool design