Skip to main content
The hosted AdsMCP endpoint is:
This reference documents the tools currently registered by that endpoint. A client can confirm the contract with MCP tools/list after authenticating.

​
Registered tools

These are the registered MCP names. Some client interfaces display dots as underscores—for example, ads_serve—but integrations should use the names returned by their client’s tool list. There is no ads.report or ads.track tool.

​
ads.serve

Runs one ad auction.

​
Input

Although the current tool schema also exposes slot_id, the hosted handler resolves the serving slot from placementCode. Use placementCode for ads.serve.

​
Output

The MCP content contains JSON with:
  • ad: a renderable ad, or null when no eligible demand matched
  • reason: a no-fill or error reason when no ad is returned
  • optional targeting diagnostics
An ad can include title, content, cta, click_url, impression_url, a render object, product context, and video fields. Preserve the sponsored disclosure and use click_url exactly as returned. Do not prefetch or programmatically trigger click URLs.

​
ads.prefetch

Runs several independent ad requests concurrently.

​
Input

Pass a batch array containing at most 10 contexts. Every context requires:
  • conversationId
  • userKey
  • surface
Contexts can also include messages, intent, sentiment, depth, language, geo, and preferHtml.

​
Output

Returns the filled ads, prefetched_count, and a truncated flag. Individual no-fills and failed requests are omitted from the returned ads array.

​
ads.diagnostics

Explains auction eligibility for a real publisher slot. Use this during integration debugging, not in the end-user request path.

​
Input

The tool returns the upstream eligibility explanation or a structured error.

​
get_video_ad_vast

Runs a wait-state video auction and returns VAST XML.

​
Input

​
Output

Returns vast_version, vast_xml, and status. A filled response also includes auction_id. No-fill and upstream-error responses still contain a valid empty VAST document.

​
confirm_ad_delivery

Confirms that an auction was presented. The operation is idempotent.

​
Input

Each tracker summary can contain url, fired_at, status_code, and error; only url is required. The server records the confirmation and performs any demand-side billing reconciliation. Publishers never receive or call demand-side billing URLs directly.
get_video_ad_vast returns auction_id on fill. Do not infer an auction ID from another field when a tool response does not explicitly supply one.