API DocsKnowledge BaseSystem StatusContact SupportContact Sales
Knowledge Base
  1. Additional Features

MCP Server

Connect AI agents to Kevel through a secure MCP server for read and write access to campaign, inventory, reporting, and forecasting data.

Connect AI agents like ChatGPT, Claude, or custom clients to Kevel through a standard Model Context Protocol (MCP) server.

Kevel's MCP server gives agents secure, read and write access to campaign, inventory, reporting, forecasting, and related network data using a Kevel API key.

Overview

Kevel's MCP server lets AI agents query Kevel through a standard MCP interface instead of integrating directly with multiple APIs. The server provides both read and write access, so agents can explore and analyze data as well as create and update entities across your network. Write access is enabled by default and can be disabled on request to run the server in read-only mode.

📘

What write access includes

Update tools can set IsDeleted to soft-delete advertisers, campaigns, flights, ads, creatives, priorities, channels, and sites. Targeting rules can be deleted outright. In read-only mode the server removes every write tool: each create, update, upsert, patch, and delete tool. The tools that start a report or a forecast, and the tool that requests an ad decision, stay available. They produce queued results or a decision and do not change network entities.

Use cases include:

  • Reviewing advertisers, campaigns, flights, ads, creatives, and targeting
  • Querying inventory such as channels, sites, and zones
  • Running and polling reports
  • Checking forecasts and ad products
  • Reading catalog, content, and job data
  • Requesting ad decisions for analysis or testing

How to use

Before you begin

You will need:

  • Access to the Kevel Management UI
  • A valid Kevel API key

To generate an API key:

  • Open the Kevel Management UI
  • Go to Settings
  • Generate or copy an API key
📘

Please note

We recommend generating a new API key specifically for MCP usage rather than reusing a shared key. This makes it possible to audit on a per-user basis, since each key can be associated with a single user and use case.

Connect to the MCP server

Add the Kevel MCP server to your MCP-compatible client using:

Server URL: https://mcp.kevel.com/
Authentication: OAuth 2.1 sign-in with a Kevel API key

After adding the server, your client opens a Kevel sign-in page. Paste your API key from the Kevel Management UI there. Kevel keeps the key on its side and gives your client a token, not the key.

The exact setup flow depends on the client you are using. Setup steps for the most common clients are below.

Claude

Custom remote MCP connectors are available on Claude Pro, Max, Team, and Enterprise plans. On Team and Enterprise plans, an Owner must add the connector at the organization level before individual members can enable it.

  1. Open Claude in your browser and click your profile icon, then Settings.
  2. In the sidebar, click Connectors.
  3. Scroll to the bottom and click Add custom connector.
  4. Enter:
    • Name: Kevel
    • Remote MCP server URL: https://mcp.kevel.com/
  5. Click Add.
  6. Back on the Connectors page, open the new Kevel connector and connect using your Kevel API key when prompted.

Once connected, Kevel tools will appear automatically in your Claude conversations.

ChatGPT

Custom MCP connectors in ChatGPT require Developer Mode, which is available on Pro, Plus, Business, Enterprise, and Edu plans. On Business and Enterprise/Edu workspaces, an admin must first enable Developer Mode in workspace settings before users can add connectors.

  1. In ChatGPT, go to Settings → Apps & Connectors → Advanced settings.
  2. Toggle Developer Mode to ON and confirm the warning.
  3. Return to Apps & Connectors and click Add new connector.
  4. Enter:
    • Name: Kevel
    • Description: Kevel ad server (optional)
    • MCP Server URL: https://mcp.kevel.com/
  5. Complete the connector setup and authenticate with your Kevel API key when prompted.

Enabling Developer Mode disables ChatGPT memory automatically.

Cursor

Cursor supports remote MCP servers via the mcp.json configuration file. You can scope the server globally or per project.

  1. Open Cursor and go to Settings → Tools & Integrations (or Tools on the Free plan).

  2. Under MCP Tools, click Add Custom MCP. Cursor opens the mcp.json file.

    • Global config lives at ~/.cursor/mcp.json (macOS/Linux) or %USERPROFILE%\.cursor\mcp.json (Windows).
    • Project-scoped config lives at .cursor/mcp.json in your project root.

  3. Add the Kevel server entry:

    {
  "mcpServers": {
    "kevel": {
      "url": "https://mcp.kevel.com/"
    }
  }
}

  4. Save the file. Cursor will prompt you to authenticate with your Kevel API key. A green dot next to the server name indicates a successful connection.

Other clients

For client-specific setup instructions not covered above, refer to your MCP client's documentation. This is the best place to find the latest steps for MCP-compatible tools.

Your client must support OAuth 2.1 sign-in: the authorization code flow with PKCE, and dynamic client registration. The server rejects a Kevel API key sent as a request header or as a bearer token, so a client that can only send a static key cannot connect.

For an automated integration that cannot open a browser, the server also supports the OAuth client credentials grant. Send your Kevel API key as the client_secret in a request to https://mcp.kevel.com/token, with a client_id that identifies your integration. The server returns an access token and no refresh token, so request a new token when the old one expires. A client_id from dynamic client registration stops working after about a year. Contact your Kevel representative for help choosing a client ID for a long-lived integration.

Verifying the connection

In any client, ask the agent to list available tools or run a simple read, for example:

List my advertisers in Kevel.

The agent should call kevel_list_advertisers and return results from your network.

Rate limit

The server accepts up to 10 requests per second for each API key. Requests above that limit receive an HTTP 429 response with a Retry-After header of 1 second.

Available tools

Reporting (7 tools)

  • kevel_create_report — Create async queued report (returns GUID; results kept 10 days, up to 1.3 million rows)
  • kevel_get_report — Poll for queued report results
  • kevel_get_instant_counts — Real-time counts for a single entity (90-day window)
  • kevel_get_bulk_counts — Real-time counts for multiple entities
  • kevel_list_report_runs — List report execution history
  • kevel_list_scheduled_reports — List scheduled reports
  • kevel_get_scheduled_report — Get scheduled report by ID

Management (34 tools)

  • kevel_list_advertisers — List/search advertisers
  • kevel_get_advertiser — Get advertiser by ID
  • kevel_create_advertiser — Create an advertiser
  • kevel_update_advertiser — Update an advertiser (full replace)
  • kevel_list_campaigns — List/search campaigns
  • kevel_get_campaign — Get campaign by ID
  • kevel_create_campaign — Create a campaign under an advertiser
  • kevel_update_campaign — Update a campaign (full replace)
  • kevel_list_flights — List flights (filter by campaign/advertiser)
  • kevel_get_flight — Get flight by ID
  • kevel_create_flight — Create a flight under a campaign
  • kevel_update_flight — Update a flight (full replace)
  • kevel_list_ads — List ads (filter by flight)
  • kevel_get_ad — Get ad by ID
  • kevel_create_ad — Attach a creative to a flight (create ad)
  • kevel_update_ad — Update an ad (flight-creative mapping, full replace)
  • kevel_list_creatives — List creatives (filter by advertiser)
  • kevel_get_creative — Get creative by ID
  • kevel_create_creative — Create a creative under an advertiser
  • kevel_update_creative — Update a creative (full replace)
  • kevel_list_creative_templates — List creative templates
  • kevel_get_creative_template — Get creative template by ID
  • kevel_create_creative_template — Create a creative template
  • kevel_list_segments — List segments
  • kevel_get_segment — Get segment by ID
  • kevel_create_segment — Create a segment
  • kevel_update_segment — Update a segment (full replace)
  • kevel_list_priorities — List priorities (filter by channel)
  • kevel_get_priority — Get priority by ID
  • kevel_create_priority — Create a priority under a channel
  • kevel_update_priority — Update a priority (full replace)
  • kevel_list_advertiser_segments — List segments for an advertiser
  • kevel_list_flight_categories — List the categories on a flight
  • kevel_get_entity_counts — Get counts of all entity types

Inventory (19 tools)

  • kevel_list_channels — List channels
  • kevel_get_channel — Get channel by ID
  • kevel_create_channel — Create a channel
  • kevel_update_channel — Update a channel (full replace)
  • kevel_list_channel_priorities — Get priorities for a channel
  • kevel_list_channels_for_site — List channels for a site
  • kevel_list_sites — List sites (filter by channel)
  • kevel_get_site — Get site by ID
  • kevel_create_site — Create a site
  • kevel_update_site — Update a site (full replace)
  • kevel_list_zones — List zones
  • kevel_get_zone — Get zone by ID
  • kevel_create_zone — Create a zone
  • kevel_update_zone — Update a zone (full replace)
  • kevel_list_ad_types — List ad types (filter by channel)
  • kevel_create_ad_type: Create an ad type on a channel
  • kevel_list_channel_site_maps — List channel-site associations
  • kevel_create_channel_site_map — Map a site to a channel
  • kevel_update_channel_site_map — Update a channel-site map

Decision (1 tool)

  • kevel_request_decision — Request ad decisions

Forecast (8 tools)

  • kevel_create_forecast — Create a new forecast (existing/available/deliverable)
  • kevel_list_forecasts — List active forecasts
  • kevel_get_forecast — Get forecast by ID
  • kevel_list_traffic_modifiers — List traffic modifiers
  • kevel_get_traffic_modifier — Get traffic modifier by ID
  • kevel_get_forecast_network_settings — Get forecast network settings
  • kevel_list_ad_products — List ad products
  • kevel_get_ad_product — Get ad product (optionally with targeting sets)

Targeting (25 tools)

  • kevel_list_flight_segment_targeting — List segment targeting on a flight
  • kevel_get_flight_segment_targeting — Get segment targeting rule on a flight
  • kevel_create_flight_segment_targeting — Create segment targeting rule on a flight
  • kevel_update_flight_segment_targeting — Update segment targeting rule on a flight (full replace)
  • kevel_delete_flight_segment_targeting — Delete segment targeting rule from a flight
  • kevel_list_ad_segment_targeting — List segment targeting overrides on an ad
  • kevel_get_ad_segment_targeting — Get segment targeting rule on an ad
  • kevel_create_ad_segment_targeting — Create segment targeting rule on an ad
  • kevel_update_ad_segment_targeting — Update segment targeting rule on an ad (full replace)
  • kevel_delete_ad_segment_targeting — Delete segment targeting rule from an ad
  • kevel_create_flight_sitezone_targeting — Create site/zone targeting rule on a flight
  • kevel_update_flight_sitezone_targeting — Update site/zone targeting rule on a flight (full replace)
  • kevel_delete_flight_sitezone_targeting — Delete site/zone targeting rule from a flight
  • kevel_list_flight_geo_targeting — List geo targeting on a flight
  • kevel_create_flight_geo_targeting — Create geo targeting rule on a flight
  • kevel_update_flight_geo_targeting — Update geo targeting rule on a flight (full replace)
  • kevel_delete_flight_geo_targeting — Delete geo targeting rule from a flight
  • kevel_list_flight_distance_targeting — List distance targeting on a flight
  • kevel_create_flight_distance_targeting — Create distance targeting (lat/long + radius) on a flight
  • kevel_update_flight_distance_targeting — Update distance targeting on a flight
  • kevel_delete_flight_distance_targeting — Delete distance targeting from a flight
  • kevel_list_flight_day_parting — List day parting rules on a flight
  • kevel_create_flight_day_parting — Create day parting rule on a flight
  • kevel_update_flight_day_parting — Update day parting rule on a flight (full replace)
  • kevel_delete_flight_day_parting — Delete day parting rule from a flight

UserDB (2 tools)

  • kevel_read_user — Read full user record
  • kevel_get_user_segments — Get user's segment IDs

ContentDB (1 tool)

  • kevel_get_content_record — Get content record by schema/key

Catalog (8 tools)

  • kevel_list_catalogs — List product catalogs
  • kevel_get_catalog — Get catalog by ID
  • kevel_list_catalog_items — List catalog items (with search)
  • kevel_list_ad_templates: List the ad templates available for the network
  • kevel_get_catalog_item — Get catalog item by ID
  • kevel_upsert_catalog_items — Insert-or-replace catalog items in batch (1 to 1,000 items per call)
  • kevel_patch_catalog_items — Partially update catalog items in batch (1 to 100 items per call; items not already in the catalog are skipped)
  • kevel_create_ingest_url — Mint signed S3 upload URL for bulk catalog ingestion (for loads above the 1,000 item limit)

Jobs (3 tools)

  • kevel_list_jobs — List all jobs (completed jobs kept 7 days)
  • kevel_get_job — Get job by ID (completed jobs kept 7 days)
  • kevel_create_job — Submit an async batch job to create product ads

Docs (1 tool)

  • kevel_lookup_docs — Look up Kevel reference documentation

Updated 14 days ago