MCP Server

Pushnami Ads runs a Model Context Protocol (MCP) server. Connect an AI assistant such as Claude or Cursor to it, and the assistant can manage your campaigns, creatives and source bids when you ask it to, for example:

"Pause every campaign that hit its daily limit before noon."
"Clone my best creative in C0001234 three times with different titles and submit them."
"Block these 40 sources on all my US mobile campaigns."
"Raise the bid to $0.35 on the sources in this list."

The MCP server offers the same actions, rules and limits as the Campaign Management API. It can check your balance but not change it, and it does not do reporting.

Connection Details

Setting	Value
Server URL	`https://ads-api.pushnami.com/mcp`
Transport	Streamable HTTP
Authentication	OAuth sign-in with the email address and password you use for Pushnami Ads, or an API key sent as `Authorization: Bearer pnk_...`

Connect by Signing In (OAuth)

Use this with MCP clients that support OAuth sign-in. You don't need an API key.

Add https://ads-api.pushnami.com/mcp to your client as a remote (Streamable HTTP) MCP server. Leave out the Authorization header.
When your client opens the Pushnami sign-in page, sign in with the email address and password you use for Pushnami Ads. Use your email address, not a username.
If your account still has a temporary password, the sign-in page asks you to set a new one. If it asks for a verification code, enter it. If it sends you to the dashboard to finish setting up your account, do that, then connect again.

Supported Clients

Each of these clients opens the Pushnami sign-in page, where you sign in with the email address and password you use for Pushnami Ads.

Client	How to add the server
Claude (claude.ai, Claude Desktop, mobile)	Add a custom connector with the server URL
ChatGPT	Add a connector with the server URL
Claude Code	`claude mcp add --transport http pushnami-ads https://ads-api.pushnami.com/mcp`
Cursor (desktop, web and Cloud Agents)	The Cursor config without `headers`
VS Code with GitHub Copilot (desktop and vscode.dev)	The VS Code config without `inputs` and `headers`
OpenAI Codex CLI, Gemini CLI, Goose, Zed, MCP Inspector CLI	Add the server URL as a remote MCP server in the client's MCP settings

If your client isn't listed, use an API key.

What to know:

It is for MCP only. The REST API at /v1 still needs an API key.
Your client stays signed in for 14 days. It renews the session on its own during that time. After that, you sign in again.
The connection can make changes, like a write key. Keep your client's confirmations on (see Staying in Control).
The same rules apply. A signed-in connection has the same limits, safeguards and pause rules as an API key.
There is no key to expire, so key expiry warnings don't apply.
Only advertiser logins can connect.

Connect with an API Key

Use an API key with clients that don't support OAuth sign-in but let you set a request header, and for the REST API. The setups below use a key. Create a key on the API Access page in the dashboard (or from the command line), and pick its scope:

read keys let the assistant look but not change anything. It only sees the read tools.
write keys let it make changes. Use one only when you want the assistant to act.

Claude Code

claude mcp add --transport http pushnami-ads https://ads-api.pushnami.com/mcp \
  --header "Authorization: Bearer pnk_..."

Claude Desktop

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "pushnami-ads": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://ads-api.pushnami.com/mcp",
        "--header", "Authorization:${PUSHNAMI_ADS_AUTH}"
      ],
      "env": { "PUSHNAMI_ADS_AUTH": "Bearer pnk_..." }
    }
  }
}

Restart Claude Desktop. pushnami-ads appears in the tools menu.

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "pushnami-ads": {
      "url": "https://ads-api.pushnami.com/mcp",
      "headers": { "Authorization": "Bearer pnk_..." }
    }
  }
}

VS Code (GitHub Copilot)

Add to .vscode/mcp.json:

{
  "inputs": [
    { "type": "promptString", "id": "pushnami-key", "description": "Pushnami Ads API key", "password": true }
  ],
  "servers": {
    "pushnami-ads": {
      "type": "http",
      "url": "https://ads-api.pushnami.com/mcp",
      "headers": { "Authorization": "Bearer ${input:pushnami-key}" }
    }
  }
}

Other Clients

Any client that supports remote MCP servers over Streamable HTTP with a custom header works. If yours only supports local (stdio) servers, use mcp-remote as shown for Claude Desktop.

Tools

Tool	Scope	What it does
`get_api_key_info`	read	Which account the key acts on, and its scope
`get_limits`	read	How much of today's change budget is left
`get_balance`	read	Your balance, how you pay, and how many days it will last at the current pace
`list_campaigns`	read	List campaigns
`get_campaign`	read	One campaign, with default bid and why it is or isn't delivering
`list_creatives`	read	A campaign's creatives, with rejection feedback
`get_creative`	read	One creative
`get_source_settings`	read	Source targeting mode, blocked/allowed sources, bid overrides
`create_campaign`	write	Create a campaign
`update_campaign`	write	Change bid, daily limit, target CPA, audience, schedule or name
`set_campaign_status`	write	Pause, activate or archive a campaign
`clone_campaign`	write	Copy a campaign, its source targeting and (optionally) its creatives
`create_creatives`	write	Add up to 20 creatives and submit them for review
`update_creative`	write	Edit a creative
`set_creative_status`	write	Pause, activate or archive a creative
`clone_creative`	write	Copy a creative, optionally changing fields
`upload_image`	write	Upload an icon or image for a creative, from a link or a file
`set_source_bids`	write	Set bids for up to 50 sources
`block_sources` / `unblock_sources`	write	Manage a block-list campaign
`allow_sources` / `disallow_sources`	write	Manage an allow-list campaign

Each tool describes its inputs to the assistant, and tools that change things are marked so your client can ask you to confirm before running them.

Staying in Control

Start with a read key. Let the assistant analyse your account first, then switch to a write key when you want it to act. (A connection made by signing in can always make changes.)
Keep confirmations on. Most clients ask before running a tool that changes something. Leave that on for archiving, budget and bid changes.
Built-in limits. An assistant can change at most 50 sources per call, a limited number of things per day, and can't more than double a bid or budget in one step. Pausing is never limited. See Limits and Safeguards.
Review is unchanged. Creatives an assistant creates or edits go through the same human review as yours, and can't be activated before approval.
One key per assistant. If an assistant does something unexpected, revoke its key without affecting anything else. See Manage Keys.
Every change is logged with the key or login that made it.

Low-Balance Warnings

When your balance is running low, the MCP server tells your assistant as soon as it connects, and repeats the warning on its tool results for the next hour, so it can mention it before launching or scaling anything. What counts as low depends on how you pay:

Prepay (wire): 7 days of spend or less left at the current pace, with the date to send the wire by.
Card: under $500 or 3 days of spend left, unless auto-funding is on. With auto-funding on you're only warned if the balance runs out anyway, which usually means a top-up failed.

Ask "How's my balance?" at any time to run get_balance. The assistant can't add funds; do that in the dashboard or by wire.

Key Expiry

This applies only when you connect with an API key. A key lasts 30, 90 or 365 days (365 by default). In the last 14 days, tool results carry a key_expiry_warning, and the assistant is told to pass it on to you. Renew the key on the API Access page. It keeps the same value, so you don't need to change your client's configuration. See Expiry and Renewal.

Troubleshooting

Problem	Fix
`401 unauthorized`	With an API key: the key is wrong, expired or revoked. Renew an expired key on the API Access page; it keeps the same value. Create a new key if it was revoked. With OAuth sign-in: the session ended. Reconnect in your client and sign in again.
The assistant only has read tools	The key has `read` scope. Create a `write` key.
`403` "origin is not allowed"	The request came from a web page. Use a desktop, CLI or server-side MCP client.
A tool returns `conflict`	The change isn't allowed in the current state or by a safeguard. The message says why, for example "only a paused creative can be activated". See Conflicts.
A tool returns `rate_limited`	Too many calls, a daily limit was reached, or another change to the same object is still running. For the first, wait `retry_after_seconds`. For a daily limit, `get_limits` shows which one; make further changes in the dashboard or wait for the reset at 00:00 UTC.

Agent Guide: a page written for AI agents to read
Campaign Management API
Spend Report API for reporting

Connection Details​

Connect by Signing In (OAuth)​

Supported Clients​

Connect with an API Key​

Claude Code​

Claude Desktop​

Cursor​

VS Code (GitHub Copilot)​

Other Clients​

Tools​

Staying in Control​

Low-Balance Warnings​

Key Expiry​

Troubleshooting​

Related​