Gam Seller MCP Node

What gam-seller-mcp-node does

gam-seller-mcp-node MCP server presents publisher-defined advertising product families to buyer agents through a constrained MCP interface. The catalog, buyer grants, entitlements, and firm list prices come from operator-managed configuration. Buyers can see only the product families and surfaces they are entitled to access.

The server exposes three discovery and availability operations: discover_products, get_forecast, and check_availability. Product discovery returns configured formats, channels, sites, and firm prices where available. Forecasts use Low, Mid, or High availability buckets. Availability checks compare a requested volume and period with the latest forecast, returning an available, partial, or unavailable result.

The two buyer-scoped write operations are create_intent and revoke_intent. An intent records a time-limited buying commitment at the current firm price, but it is not a Google Ad Manager order or an inventory reservation. Buyers can revoke their own active intents. A well-known capabilities document provides the node identity, privacy posture, and a signed capability statement.

How it works

Every authenticated request is processed through replay detection, RS256 token validation, default-deny policy checks, entitlement and scope checks, rate limiting, domain processing, response disclosure validation, and audit recording. Requests normally require client_request_id; operators can disable that requirement with MCP_REQUIRE_IDEMPOTENCY_KEY=0, which reopens the omission bypass described in the project documentation.

The audit ledger is append-only, hash-chained, and records both allowed and denied requests with buyer pseudonyms. Startup checks detect a corrupted or modified ledger and refuse service rather than resetting it. create_intent also verifies that the submitted price_ref still matches the family’s current firm price.

Forecast data can be synthetic, seeded from configured values, or obtained from an optional read-only Google Ad Manager ForecastService snapshot. The catalog remains operator configuration, and the server does not perform ad-server writes.

Setup and configuration

The default transport for MCP clients is stdio. A client can launch the package with npx -y gam-seller-mcp-node. Running without custom configuration starts a bundled pilot-publisher example and prints a demo buyer token to stderr. Authenticated buyer tools still require that token.

For a deployment-specific setup, set MCP_CONFIG_DIR to a directory containing the publisher configuration. The documented files cover deployment metadata, product catalog and buyer grants, surface entitlements, firm pricing, optional seeded forecasts, and optional GAM connection and targeting details. Invalid configuration fails closed. From source, the project can be built with npm and started over HTTP on 127.0.0.1:3900; Docker Compose uses the same local address and persists keys and audit data.

The gam-seller-mcp-node MCP server can also be exercised with the included pilot script or demo, which walks through discovery, forecasting, commitment, revocation, and governed refusals.

Tools and capabilities

• well_known_capabilities: returns the signed capability and identity document.
• discover_products: lists entitled product families and configured firm prices without exposing raw inventory or deal identifiers.
• get_forecast: returns coarse availability buckets.
• check_availability: evaluates requested volume and timing against the latest forecast using rounded values.
• create_intent: records a buyer-scoped, TTL-bound intent after price validation.
• revoke_intent: withdraws one of the calling buyer’s active intents.

Limitations and notes

The system is a governed control-plane prototype for future GAM integration. It does not create orders, alter line items, or place inventory holds. It also withholds exact impression counts, CPM curves, floor prices, audience data, other buyers’ bookings, raw inventory, deal IDs, and internal identifiers. Without a live GAM connection, forecast results are synthetic; configured prices fail closed when expired. Rate limiting applies to every authenticated tool, including intent operations.