juan-sibbo/gam-seller-mcp-node

A Model Context Protocol server that exposes sell-side ad inventory to buyer-side AI agents: discovery, firm pricing, and a buyer-scoped soft commitment primitive. No writes to an ad server exist. Forecasts can come live from Google Ad Manager (opt-in, read-only ForecastService snapshot); the catalog is operator config, and without a GAM connection forecast data is synthetic.
---
What problem does this solve?
Sell-side ad inventory (availability, pricing, product structure) lives inside ad servers that hold commercially sensitive and sometimes personal data. Giving an AI buyer agent direct API access to GAM or a similar system creates three risks:
| Risk | Without this project | With this project |
|------|---------------------|-------------------|
| Data over-exposure | Agent can read raw avails, deal IDs, exact floor prices | Only coarse buckets and pre-declared families |
| Accidental writes | Agent SDK can create orders, modify line items | No ad-server writes exist; the only write is a buyer's own soft commitment, which can never become a GAM order or an inventory hold |
| No accountability | API calls are logged but not auditable | Hash-chained audit ledger; every allow/deny recorded |
How it works
A buyer agent connects via MCP and gets five tools — three read-only, plus a buyer-scoped
commitment primitive (create/revoke) that is the sole write surface:
Every call flows through the same pipeline before any domain logic runs:
Each request-path gate rejects on failure. One honest caveat to the diagram above:
- **client_request_id** (the replay-guard deduplication key) is **required by default** on every
authenticated surface since v0.9.0 — a request without it is rejected, so SEC-GATE-3 cannot be
bypassed by omission. An operator can explicitly opt out for legacy clients with
MCP_REQUIRE_IDEMPOTENCY_KEY=0, which reopens that bypass.
The rate-limit stage covers **every** authenticated tool — the read surfaces, create_intent,
and revoke_intent — so no authenticated surface bypasses it.
A corrupted or tampered on-disk ledger is **detected on startup** and the node refuses to serve
(fail-closed on load, plus a chain-integrity verify before the first request) rather than
resetting to an empty chain.
create_intent runs the same gates and adds one more before it records anything: the buyer's
price_ref must match the family's current firm price, or the request is rejected.
Quick start
> **Run a full pilot in one command.** scripts/pilot.sh brings the node up on your config with
> production guards on, mints a buyer token per entitled buyer, and prints how to drive a buyer
> agent through the whole loop (discover → forecast → commit → revoke) — see
> docs/PILOT-QUICKSTART.md. The reference buyer agent lives at
> examples/buyer-client-ts/agent.ts; hosting behind TLS is a
> filled-in-the-blanks recipe in deploy/.
Install in an MCP client (via npx)
Add the server to your MCP client (Claude Desktop, Claude Code, Cursor, …):
Or run it directly (stdio transport — the default for MCP clients):
> **Demo mode.** With no config of your own, the node boots on a bundled
> pilot-publisher example (illustrative catalog, prices and forecasts) and says so
> on stderr — it starts instead of failing, so you can try the tools immediately.
> Because buyer surfaces always require a token (there is no anonymous path, even in
> demo), the node **prints a ready-to-use demo buyer token** on startup: copy it and pass
> it as the token argument to discover_products / get_forecast to see the example
> families, prices and forecasts.
>
> For a real deployment, point MCP_CONFIG_DIR at a directory holding your own
> deployment.json, catalog.json, entitlements.json and pricing.json:
>
>
From source
Run the full buyer-agent walkthrough (scripted demo) — the five native tools driven over a real
in-process MCP transport, ending in the governed refusals (fail-closed auth, Default-Deny,
fail-closed pricing) and a verified audit chain:
With Docker
The node starts on 127.0.0.1:3900. The well-known document is at
/.well-known/seller-mcp-capabilities. Persistent volumes for keys and audit data are
pre-configured in docker-compose.yml.
Configure for your publisher
Four JSON files drive all publisher-specific behaviour — no code changes needed. Place them
in config/ (from-source) or in the directory named by MCP_CONFIG_DIR (npx/containerised):