> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adgentek.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AdsMCP tool reference

> Inputs and behavior for the tools registered by the hosted AdsMCP server.

The hosted AdsMCP endpoint is:

```text theme={null}
https://mcp.adgentek.ai/mcp
```

This reference documents the tools currently registered by that endpoint. A client can confirm
the contract with MCP `tools/list` after authenticating.

## Registered tools

| Tool | Purpose |
| - | - |
| `ads.serve` | Run one ad auction and return a renderable ad or no-fill result |
| `ads.prefetch` | Run up to 10 ad requests concurrently |
| `ads.diagnostics` | Explain ad eligibility for a publisher slot |
| `get_video_ad_vast` | Run a wait-state video auction and return negotiated VAST XML |
| `confirm_ad_delivery` | Confirm a rendered auction and perform server-side billing reconciliation |

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

| Field | Type | Required | Description |
| - | - | - | - |
| `conversationId` | string | Yes | Stable conversation identifier |
| `userKey` | string | Yes | Anonymous or authenticated user identifier |
| `surface` | string | Yes | `conversational`, `search`, `voice`, `creative`, or `web` |
| `messages` | object\[] | No | Conversation context with `role` and `content` fields |
| `intent` | string | No | `purchase`, `research`, `support`, or `informational` |
| `sentiment` | number | No | Score from -100 through 100 |
| `depth` | integer | No | Conversation message count |
| `language` | string | No | ISO language code |
| `geo` | string | No | ISO country code |
| `placementCode` | string | No | Publisher slot code |
| `format_preferences` | string\[] | No | Narrow the formats already approved for the surface |
| `preferHtml` | boolean | No | Request HTML render data when available |
| `extras` | object | No | Additional context |

> [!WARNING]
>
> 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

| Field | Type | Required | Description |
| - | - | - | - |
| `surface` | string | Yes | One of the supported surface values |
| `slot_id` | string | Yes | Real publisher placement or slot ID |
| `placementCode` | string | No | Backward-compatible alias for `slot_id` |
| `conversationId` | string | No | Conversation identifier |
| `userKey` | string | No | User identifier |
| `messages` | object\[] | No | Conversation context |
| `intent` | string | No | Detected intent |
| `sentiment` | number | No | Sentiment score |

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

| Field | Type | Required | Description |
| - | - | - | - |
| `vast_version` | string | No | `2.0`, `3.0`, or `4.2`; defaults to `3.0` |
| `surface` | string | No | Defaults to `ai_generation_wait` |
| `format` | string | No | Defaults to `video` |
| `slot_id` | string | No | Publisher slot or placement ID |
| `placementCode` | string | No | Alias for `slot_id` |
| `session_id` | string | No | Stable wait-state session ID |
| `estimated_duration_seconds` | integer | No | Expected wait from 5 through 120 seconds |
| `intent_bucket` | string | No | Intent classification |
| `iab_categories` | string\[] | No | Relevant IAB categories |
| `keywords` | string\[] | No | Context keywords |
| `debug` | boolean | No | Requires the `vast:debug` key scope |

### 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

| Field | Type | Required | Description |
| - | - | - | - |
| `auction_id` | string | Yes | Auction identifier returned by a response that supplies one |
| `delivered_at` | string | No | ISO timestamp; defaults to server time |
| `tracker_fire_summary` | object\[] | No | Per-URL status for browser-side trackers the publisher fired |

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.

> [!NOTE]
>
> `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.