mcp-server

@kadam-net/mcp-server

MCP server for Kadam ad network — manage campaigns, creatives, audiences, sites, and analytics via AI agents.

Built on the Model Context Protocol (MCP), the open standard for connecting LLMs to external tools and data.

Install (one click)

Cursor

Or add manually to .cursor/mcp.json:

{
  "mcpServers": {
    "kadam": {
      "command": "npx",
      "args": ["-y", "@kadam-net/mcp-server"],
      "env": {
        "KADAM_ADV_API_KEY": "your-advertiser-api-key",
        "KADAM_PUB_API_KEY": "your-publisher-api-key"
      }
    }
  }
}

Claude Code

claude mcp add kadam -- npx -y @kadam-net/mcp-server

Then set the env var: export KADAM_ADV_API_KEY=your-key

Claude Desktop

Download → double-click → Install. Or add manually to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "kadam": {
      "command": "npx",
      "args": ["-y", "@kadam-net/mcp-server"],
      "env": {
        "KADAM_ADV_API_KEY": "your-advertiser-api-key",
        "KADAM_PUB_API_KEY": "your-publisher-api-key"
      }
    }
  }
}

Any MCP client (universal one-liner)

npx add-mcp @kadam-net/mcp-server

Docker

docker run -i --rm \
  -e KADAM_ADV_API_KEY=your-key \
  kadam/mcp-server:latest

npm global

npm install -g @kadam-net/mcp-server
KADAM_ADV_API_KEY=your-key kadam-mcp-server

Configuration

Variable	Required	Description
KADAM_ADV_API_KEY	One of two	Advertiser API key from partners.kadam.net -> Profile -> API
KADAM_PUB_API_KEY	One of two	Publisher API key from pub.kadam.net -> Profile -> API
KADAM_ADV_API_BASE	No	Advertiser API URL (default: https://partners.kadam.net/api/v1)
KADAM_PUB_API_BASE	No	Publisher API URL (default: https://pub.kadam.net/api)
LOG_LEVEL	No	Log level: trace, debug, info, warn, error, fatal (default: info)

At least one API key must be provided in stdio mode. In HTTP mode, tokens are passed per-request via Bearer authentication.

Role-based catalog

The tool catalog matches the role of the bearer. Once per session (and once per process in stdio mode) the server calls GET /api/v1/access on the advertiser API, which answers { impersonation: bool }:

Bearer	impersonation	Catalog
Advertiser API key, or a cabinet JWT with sub only	false	75 tools; create_campaign / update_campaign have no manager-only fields
Cabinet JWT with act.sub (a Kadam manager acting for the client)	true	80 tools (adds the five marked "manager-only" below); campaign writes accept hasCorrectPostback, isDirectTrafficPriority, allowMultiAds
Publisher API key	n/a	17 publisher tools; the publisher API has no impersonation

This is a catalog hint, not a gate: the Kadam API enforces the same rule on every call (403 / 422 for a client token). If /access cannot be reached, the session gets the client catalog — the smaller one is always safe to show.

HTTP Transport (multi-tenant deployment)

For server-side deployment serving multiple users:

Variable	Required	Description
MCP_TRANSPORT	No	"stdio" (default) or "http"
MCP_HTTP_PORT	No	HTTP port (default: 8080)
MCP_HTTP_HOST	No	Bind address (default: 0.0.0.0)
KADAM_ADV_DOMAIN	No	Advertiser domain for PRM (default: https://partners.kadam.net)
KADAM_PUB_DOMAIN	No	Publisher domain for PRM (default: https://pub.kadam.net)

docker run -d --name kadam-mcp \
  -e MCP_TRANSPORT=http \
  -p 8080:8080 \
  kadam/mcp-server:latest

Connecting via HTTP (Cursor / Claude)

{
  "mcpServers": {
    "kadam-adv": {
      "url": "https://partners.kadam.net/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_ADV_API_KEY"
      }
    }
  }
}

Connecting via OAuth (ChatGPT)

Add https://partners.kadam.net/mcp (advertiser) or https://pub.kadam.net/mcp (publisher) as Server URL in ChatGPT settings. OAuth discovery, registration, and login happen automatically.

Tools (80)

Advertiser Tools (63)

Requires KADAM_ADV_API_KEY.

Dictionaries

Tool	Description	Annotations
kadam_adv_get_dictionary	Reference dictionary: campaign types, browsers, platforms, devices, connections, categories, isps, conversion templates, countries, regions, cities	readOnly

Campaigns

Tool	Description	Annotations
kadam_adv_list_campaigns	List campaigns with filters (folder, status, type, date, search) and pagination	readOnly
kadam_adv_get_campaign	Get full campaign configuration by ID: landing page URL, bids per country, budgets, targeting, frequency caps, schedule, conversion settings	readOnly
kadam_adv_create_campaign	Create campaign with full targeting (countries, devices, OS, browsers, age, gender, audiences); dryRun: true validates only	—
kadam_adv_update_campaign	Update any campaign fields by ID	—
kadam_adv_set_campaign_status	Bulk status change (active/paused/archived/restored) for comma-separated IDs; reports per-ID result	idempotent
kadam_adv_delete_campaigns	Bulk delete of archived campaigns by comma-separated IDs; requires confirm: true, reports per-ID result	destructive
kadam_adv_move_campaigns	Move campaigns to a campaign group by comma-separated campaign IDs and target group ID	idempotent
kadam_adv_copy_campaign	Copy a campaign into a campaign group: settings and bids are cloned, the copy starts paused and re-enters moderation. Optional pricing-model switch, push <-> in-page push cross-format copy, autorules and per-site bids	—
kadam_adv_bulk_replace_urls	Find and replace a landing-URL fragment across campaigns and their creatives. Manager-only (impersonation sessions); supports dryRun	destructive
kadam_adv_set_campaign_rss	Point a native campaign at an RSS feed to import creatives, or stop the import with an empty link	idempotent
kadam_adv_set_easy_start	Turn Easy Start (curated site set) on or off for a campaign. Manager-only (impersonation sessions)	idempotent
kadam_adv_get_blocked_traffic_sources	Traffic sources rejecting a campaign, split into category blocks and moderation-tag blocks. Manager-only (impersonation sessions)	readOnly
kadam_adv_get_traffic_forecast	Bid-to-traffic curve for a targeting set from yesterday's auction. An empty curve means the forecast could not be built, not that traffic is zero	readOnly

Bid Management

Tool	Description	Annotations
kadam_adv_update_campaign_bid	Update bid for a single campaign (lightweight, no full payload). Falls back to current countries if omitted	idempotent
kadam_adv_bulk_update_bids	Update bids for multiple campaigns at once (all must share the same pricing model)	idempotent
kadam_adv_block_sites	Stop or resume buying sites (zones) in campaigns	—
kadam_adv_update_site_bids	Set per-site (zone) bids: static (0.05), multiplier (x1.5), or remove (0)	idempotent

Campaign Folders

Tool	Description	Annotations
kadam_adv_list_campaign_folders	List folders with campaign counts and budgets	readOnly
kadam_adv_get_campaign_folder	Get a single folder: name, archived state, budgets	readOnly
kadam_adv_create_campaign_folder	Create a new folder (name 1-50 chars)	—
kadam_adv_update_campaign_folder	Partial update: rename and/or change budgets and distribution	—
kadam_adv_set_campaign_folder_status	Bulk action for comma-separated IDs: activate/pause campaigns, archive or restore folders with their campaigns; returns per-folder result	idempotent

Creatives

Tool	Description	Annotations
kadam_adv_list_creatives	List creatives by campaign, status, or search query	readOnly
kadam_adv_create_creative	Create creative for a campaign: image, HTML5 archive, video file or VAST tag (goes through moderation)	—
kadam_adv_update_creative	Update creative fields	—
kadam_adv_set_creative_status	Bulk status change for creatives: active/paused/archived/restored; returns per-creative result	idempotent
kadam_adv_get_creative_test_conversion	Signed links to test a creative's conversion tracking (test click + frame preview)	—
kadam_adv_upload_bulk_images	Stage images for a bulk creative batch (async, returns a job)	—
kadam_adv_create_bulk_creatives	Turn staged images into creatives in several campaigns at once (async, returns a job)	—
kadam_adv_get_bulk_job	State of a bulk batch: staged images, refusals, per-row outcome	—
kadam_adv_copy_creatives	Copy creatives into other campaigns (creatives × targets copies), originals untouched	—
kadam_adv_move_creatives	Move creatives to another campaign of the same format and pricing model; they lose per-geo bids and return to moderation	—
kadam_adv_get_creative_blocked_sources	Traffic sources that reject one creative, split by category and moderation tag. Manager-only (impersonation sessions)	—
kadam_adv_set_creative_bids	Replace the creatives' own per-country bids; countries left out fall back to the campaign bid	—
kadam_adv_delete_creatives	Bulk delete of archived creatives by comma-separated IDs; requires confirm: true, reports per-ID result	destructive

Audiences

Tool	Description	Annotations
kadam_adv_list_audiences	List audiences with search and sorting	readOnly
kadam_adv_get_audience	Get detailed audience info by ID	readOnly
kadam_adv_create_audience	Create audience (pixel, code, fingerprint, or S2S)	—
kadam_adv_update_audience	Update audience settings	—
kadam_adv_get_filtered_audience_sources	Audiences usable as sources of a filtered audience. Manager-only (impersonation sessions)	—
kadam_adv_get_audience_params	Hardcoded parameters a pixel/S2S audience substitutes into its code	—
kadam_adv_set_audience_params	Replace the hardcoded parameters of a pixel/S2S audience	—
kadam_adv_delete_audience	Delete audience permanently (requires confirm: true)	destructive

Finance & Statistics

Tool	Description	Annotations
kadam_adv_list_finance_operations	Transaction history (deposits, charges, refunds)	readOnly
kadam_adv_get_stats	Unified statistics — 3 report types via reportType param: custom (report builder with dimension/metric mapping), sites (per-site breakdown), postbacks (conversion logs)	readOnly

Publisher Tools (17)

Requires KADAM_PUB_API_KEY.

Sites (Sources)

Tool	Description	Annotations
kadam_pub_list_sources	List publisher sites with stats	readOnly
kadam_pub_create_source	Add a new site (starts verification flow)	—
kadam_pub_get_source	Get detailed site info	readOnly
kadam_pub_update_source	Update site name	—
kadam_pub_set_source_status	Change site status (active/paused/archived/unarchived)	idempotent

Ad Units

Tool	Description	Annotations
kadam_pub_list_ad_units	List ad units for a site, filter by format (native/banner/push/popunder/inpagepush)	readOnly
kadam_pub_set_ad_unit_status	Change ad unit status (active/paused/archived/restored)	idempotent

User & Statistics

Tool	Description	Annotations
kadam_pub_get_user_info	Get publisher account info and balance	readOnly
kadam_pub_get_stats	Publisher statistics with human-readable dimension/metric mapping	readOnly

Kadam Smart Mediation

Selling an ad unit's traffic through outside ad networks alongside Kadam demand. The API, the code and the report dimensions call it plain mediation. Read kadam://reference/mediation first; split the income in kadam_pub_get_stats with groupBy=network and the kadam_revenue / mediation_revenue metrics.

Tool	Description	Annotations
kadam_pub_list_mediation_networks	Catalog of networks, which have an account, and what an ad unit already runs	readOnly
kadam_pub_connect_mediation_network	Attach a network to an ad unit (resolves account and placement itself)	—
kadam_pub_update_mediation_network	Change geo, unique cap, proxy policy, tag template, placement or account	—
kadam_pub_set_mediation_network_status	active / paused for a connection	idempotent
kadam_pub_retest_mediation_network	Restart the forced test share (1-50%); starts a new measurement epoch	—
kadam_pub_disconnect_mediation_network	Remove a connection (requires confirm)	destructive
kadam_pub_update_mediation_network_account	Rotate the network API key, rename or disable the account	—
kadam_pub_delete_mediation_network_account	Remove a network account (requires confirm)	destructive

Resources (9)

Static reference data the agent can read before calling tools:

URI	Description
kadam://reference/campaign-types	All ad format types with IDs, features, pricing, and creative specs
kadam://reference/pricing-models	CPC, CPM, CPV, CPA Target with IDs and descriptions
kadam://reference/creative-formats	Creative requirements per campaign type
kadam://reference/ad-unit-types	Publisher ad unit formats with IDs
kadam://reference/site-states	Publisher site lifecycle states
kadam://reference/mediation	Outside ad networks: accounts, placements, connections, test share, income split
kadam://reference/report-dimensions	Available dimensions and metrics for statistics tools
kadam://reference/api-overview	General Kadam API capabilities overview

Prompts (4)

Pre-built workflow templates that guide the agent through multi-step operations:

Prompt	Description	Arguments
kadam_launch_campaign	Step-by-step campaign creation (check types -> create folder -> create campaign -> add creatives)	type, name, url, budget
kadam_campaign_performance	Campaign performance analysis with optimization recommendations	campaignId, period
kadam_optimize_sites	Analyze site performance and suggest blacklist/whitelist changes	campaignId, minClicks, maxCPA
kadam_account_overview	Full account overview — campaigns, spend, top performers	—

Architecture

src/
├── index.ts                  # Entry point, server instructions, transport
├── config.ts                 # Zod-validated env config with cache
├── errors.ts                 # AuthError class
├── logger.ts                 # Pino structured logging (stderr)
├── output-formatter.ts       # Text formatting + 50KB truncation
├── middleware/
│   └── tool-wrapper.ts       # Auth, error handling, logging middleware
├── api/
│   ├── http-client.ts        # Generic HTTP client with retry/429/timeout
│   ├── partners-client.ts    # Advertiser API (lazy singleton)
│   └── pub-client.ts         # Publisher API (lazy singleton)
├── utils/
│   ├── pagination.ts         # Shared pagination extraction
│   ├── cache-once.ts         # Generic async cache-once utility
│   └── dimension-mapper.ts   # Stats dimension name→ID resolution
├── types/
│   ├── common.ts             # Shared types (ApiListResponse, ReportConfig)
│   ├── advertiser.ts         # Campaign, Creative, Audience types + maps
│   ├── publisher.ts          # Source, AdUnit, PubUser types + maps
│   └── tool-module.ts        # ToolModule interface
├── tools/
│   ├── advertiser/           # 63 tools across 14 modules
│   └── publisher/            # 17 tools across 6 modules
├── resources/                # 9 reference resources
└── prompts/                  # 4 workflow prompts

Key Design Decisions

• ToolWrapper middleware — centralized auth validation, error formatting, and logging for all 80 tools
• Lazy singleton API clients — one HttpClient instance per product, created on first use
• Output truncation — hard 50KB limit per response with maxResults (default 25, max 100) to prevent LLM context overflow
• Human-readable output — formatted tables, aligned entities, pagination metadata instead of raw JSON
• Tool annotations — readOnlyHint, destructiveHint, idempotentHint to guide agent behavior
• Server instructions — usage patterns and constraints sent to the LLM on connection
• Dimension mapping — stats tools accept human-readable names ("clicks", "spend") and resolve them to API IDs internally
• Role-shaped catalog — the bearer is forwarded untouched, and its role is read once per session from GET /access (see "Role-based catalog"). Tools declare requires: "impersonation" and ToolWrapper skips them for client sessions; campaigns.ts adds the manager-only campaign fields to its schemas only under impersonation. Nothing is enforced here — the API still answers 403 / 422 to a client token — so the catalog can never be wider than the key's real rights, only narrower when /access is unreachable

Development

Prerequisites

• Node.js >= 18
• npm

Setup

git clone https://github.com/kadam-official/mcp-server.git
cd mcp-server
npm install
cp .env.example .env  # Fill in your API keys

Commands

npm run dev             # Watch mode with tsx
npm run build           # Production build with Vite
npm run start           # Run built server
npm run typecheck       # TypeScript check
npm run lint            # ESLint
npm run format          # Prettier
npm test                # Run 82 tests
npm run test:coverage   # Tests with V8 coverage
npm run inspect         # MCP Inspector (visual debugger)

Testing

202 tests across 23 files using Vitest + MCP SDK InMemoryTransport:

• Unit tests — output formatter, config, HTTP client (mocked fetch)
• Middleware tests — ToolWrapper auth, error formatting, logging
• Integration tests — full server with all 72 tools, 8 resources, 4 prompts via in-memory MCP client
• Tool handler tests — each tool module with mocked API clients

npm test
# Test Files  23 passed (23)
#      Tests  202 passed (202)

MCP Inspector

The MCP Inspector provides a visual interface for testing:

npm run build
npm run inspect

Deployment

Docker

docker build -t kadam-mcp-server .
docker run -i --rm -e KADAM_ADV_API_KEY=... kadam-mcp-server

CI/CD

The .gitlab-ci.yml pipeline includes:

• lint — ESLint + TypeScript check
• test — Vitest with coverage
• build — Vite production build
• publish — npm publish + Docker push (manual trigger)

License

MIT