@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

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 }:

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:

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

Campaigns

Bid Management

Campaign Folders

Creatives

Audiences

Finance & Statistics

Publisher Tools (17)

Requires KADAM_PUB_API_KEY.

Sites (Sources)

Ad Units

User & Statistics

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.

Resources (9)

Static reference data the agent can read before calling tools:

Prompts (4)

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

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