Skip to content

Quickstart: Serve ads from an MCP agent

This quickstart shows you how to add the AdKit MCP server and the Ad Skill to an agent whose host supports the Model Context Protocol (MCP), such as Claude Desktop, Claude Code, or the OpenAI Agents SDK. The server gives the agent tools to fetch and report in-chat ads, and the skill tells it when to use them. It takes about five minutes. If your bot calls a model API with its own tool loop, see the System-prompt quickstart.

Before you begin

  1. Get an Advertising.chat account. If you don't have one, request access.
  2. In the console, in the Monetize section, click Get Started, and copy your key from 1 ยท Your fetch key.
  3. Install Node.js 18 or later, which runs the server through npx.

Add the MCP server

  1. Add the server to your host's MCP configuration. In the mcpServers format that Claude Desktop and most hosts use, the entry is:

    {
  "mcpServers": {
    "adchat": {
      "command": "npx",
      "args": ["-y", "@advertising-chat/mcp"],
      "env": {
        "ADCHAT_API_KEY": "YOUR_FETCH_KEY"
      }
    }
  }
}

  2. Restart the host. The agent now has three tools:

    Tool What it does
    fetch_ad Fetches one ad for the conversation. Takes a conversation_context summary, used only to select the ad, and an anonymous subscriber identifier for frequency caps. Returns the ad with click-tracking URLs and a disclosure reminder, or no_ad.
    record_event Reports an event for a fetched ad: click, conversion with an optional value and currency, or send, deliver, or read.
    record_reply Reports that the person chose one of the ad's replies, with the reply's postback_data from fetch_ad. A reply that accepts or declines the offer records the person's answer.

The server also reads two optional variables: ADCHAT_AD_UNIT, a default ad unit code, and ADCHAT_BASE_URL, the API base URL.

Add the Ad Skill

The tools let the agent serve ads. The Ad Skill tells it when to fetch one, how to label it, and how often. Copy the skill's instructions into your agent's system prompt or skill library.

See your first ad

  1. Ask your agent a question in its domain and let it finish answering.
  2. End the exchange, for example with "Thanks, that's all."
  3. At the pause, the agent calls fetch_ad and shows a message labeled Sponsored, with a link.
  4. Open the link. The click is recorded, and you're redirected to the advertiser.

If the agent shows no ad, fetch_ad returned no_ad, which means no ad fit the moment. To check the serving path directly, follow the REST quickstart with the sandbox ad unit.

What's next