Skip to content

Manage Offer Manager from an AI assistant

The Advertising.chat MCP server gives an AI assistant tools to work with Offer Manager: it can list your agents and moments, read and change rules and offers, and explain why a customer did or did not see an offer. It runs on your computer in any host that supports the Model Context Protocol (MCP), such as Claude Code, Claude Desktop, or Cursor, and every call runs as you, with your role in the org.

This document describes how to install the server in manage mode and sign in, which tools it provides, and how changes and deletions are confirmed. To give your customer-facing agent ad tools instead, see the MCP agent quickstart, which runs the same server in serve mode with an API key.

Before you begin

  • Offer Manager must be enabled for your org. See Availability.
  • You need a console login. To read, you need the viewer role or above. To create, change, or delete, you need the editor, admin, or owner role.
  • Install Node.js 18 or later, which runs the server through npx.

Sign in

  1. In a terminal, run:

    npx @advertising-chat/mcp login

  2. The command prints a code and opens the sign-in page in your browser. Confirm that the code matches, and sign in with your console account.

The login is cached in ~/.ads-cli and renews itself, so you sign in once per computer. The ads command-line tool uses the same cache, so signing in with either one signs in both. To sign out, run npx @advertising-chat/mcp logout.

Add the server to your host

  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": {
    "advertising-chat": {
      "command": "npx",
      "args": ["-y", "@advertising-chat/mcp", "manage"]
    }
  }
}

    In Claude Code, run claude mcp add advertising-chat -- npx -y @advertising-chat/mcp manage.

  2. Restart the host. To check the connection, ask the assistant who you are signed in as. It answers with the whoami tool.

The server works in your own org. If you belong to more than one org, set ADCHAT_ORG to the org's ID in the entry's env.

To give the assistant read access only, add --read-only after manage in args. The server then registers only the tools that read.

Tools

Each tool works with the records you see in the console. Moments and rules belong to one agent, so their tools take the agent as application. Offers are an org-wide library.

Tools What they do Kind Role
whoami, list_applications Show the signed-in user, the org, and its agents. Read Viewer
list_moments, get_moment List and read an agent's moments. Read Viewer
create_moment, update_moment Create a moment or change one. Write Editor
list_attributes, get_attribute List and read an agent's attribute catalog. Read Viewer
add_attribute Add an attribute to an agent's catalog, including one the agent doesn't send yet. Write Editor
document_attribute Set an attribute's label, description, and examples, which documents an observed attribute. Write Editor
update_attribute Change an attribute's type, enum values, or source, or retire it. Write Editor
translate_rule_text Translate an instruction in plain language into a change to one field of a rule, or to the whole rule. It answers with the change and its read-back, a clarifying question, the data that is missing, or why it can't be expressed, and saves nothing. Read Viewer
preview_rule_impact, describe_rule Estimate how much recent traffic a draft rule would match, and read a saved rule in plain language. Read Viewer
list_rules, get_rule List and read an agent's rules. Read Viewer
create_rule, update_rule Create a rule or change one. Write Editor
list_offers, get_offer List and read offers. Read Viewer
create_offer, update_offer, pause_offer, resume_offer Create an offer, change it, or stop and restart serving it. Write Editor
delete_moment, delete_attribute, delete_rule, delete_offer Delete a record. Destructive Editor
find_requests, explain_decision, get_stats Find offer requests, explain why a request got its offer or none, and read performance counts. Read Viewer
search_docs, read_doc Search and read this documentation. Read Viewer

Rule inputs use the same conditions as the console's rule editor; see the Rule reference. To change a rule from a plain-language instruction, the assistant translates it with translate_rule_text, shows you the read-back, and saves the result with update_rule or create_rule, which your host asks you to approve like any other change. The server checks a rule before it sends it, and creates a rule disabled unless you ask to launch it. Each tool maps to an Offer Manager API route.

How changes and deletions are confirmed

Each tool declares its kind to the host. Read tools are marked read-only, so most hosts run them without asking. Write tools change a record, and your host's tool approval settings decide whether it asks you first.

The four delete tools are marked destructive. Hosts that honor the marking ask you before the call runs, and the tool's description tells the assistant to confirm with you first. A deletion can't be undone. To rule out deletions entirely, run the server with --read-only.

A change made through the server is live as soon as the call returns, like a change saved in the console. Advertising.chat records the change as yours, made through the MCP server.

Settings

Variable Meaning
ADCHAT_ORG The ID of the org to work in. Default: your own org.
ADCHAT_TOKEN An access token to use instead of the cached login.

What's next