Skip to main content

MCP Political Planner tutorial

Use IQM Model Context Protocol (MCP) to interact with the Political Planner in the Planner API.

Overview​

This tutorial guides you through using IQM MCP to create a Political plan, compare its strategies, activate a proposal, and generate an insertion order (IO) and draft campaigns. It also covers Voter TV+ plans, which forecast reach across linear TV and connected TV (CTV).

The Planner MCP supports a limited set of features of the Planner API. For a comprehensive list of supported features and best practices for using the Political Planner, refer to the Political Planner tutorial and the Planner API guidelines.

Before you begin​

To create a Political proposal and generate an IO, the following are required:

  1. An account on the IQM platform
    • See Before you begin to create an account and request a Client ID and Client Secret.
  2. IQM MCP connected to your AI assistant
  3. Access to a Political Workspace
    • Political Planner requests from a Workspace outside the Political vertical are rejected.
  4. A Political Advertiser profile

About the Political Planner​

The Political Planner builds a forecast-backed media plan for a political campaign. A proposal goes through these steps:

  1. Create a plan
  2. Compare strategies
  3. Activate a proposal
  4. Generate the IO and campaigns

Voter TV+ plans start from a reach saturation graph instead, and are activated without a strategy:

  1. Get a reach saturation graph
  2. Create a plan
  3. Activate a proposal
  4. Split the CTV campaigns (optional)
  5. Generate the IO and campaigns

More resources​

Select a Political Workspace​

Select the Organization to build the proposal in before you start.

PromptResponse exampleNotes
I want to build a Political proposal with IQM's Planner. First, list the Organizations and Workspaces I can access and select my Political Workspace.MCP lists the Organizations you can access. Organization names don't show the vertical, so if none is named "Political," tell MCP which Organization to use, as in the next prompt.

Create a plan and activate a proposal​

Create a ready plan, compare the strategies IQM generates for it, and activate one into a proposal.

PromptResponse exampleNotes
We'll use SDK Test Customer.
Create a ready Political plan with these settings:
  • Name: MCP Political Planner 01
  • Objective: Reach forecasting
  • Total budget: $50,000
  • Flight: November 3, 2026 to November 30, 2026
  • Frequency cap: 3
  • Targeting: device types 20300001 and 20300004, creative types image (11) and video (14), TV auto buying off
MCP looks up the objective ID, uses US/Eastern when no timezone is given, and converts the flight to epoch milliseconds. The start date can't be in the past. A plan without location targeting targets the whole United States. If the targeting is too narrow, the plan is rejected with No strategies meet your criteria and nothing is created.
List the strategies generated for that plan. Put them in a table comparing name, strategy type, campaign count, budget, reach, impressions, and CPM, and recommend which one to activate for maximum reach.IQM generates up to three strategies for a ready plan: Maximum Reach, Balanced, and Most Economical. Broad targeting like this example's can produce a single strategy that spends only a small part of the budget. Add location targeting or audiences to get strategies that use more of it.
Activate the Maximum Reach strategy into a proposal.Activating a strategy creates a proposal and its proposed campaigns. It doesn't create any campaigns in the DSP.
Get the details for that proposal. Confirm its status is Ready (6) and that campaignGeneratable is true, then list the proposed campaigns with their name, creative type, budget, CPM, targeted reach, and targeted impressions.An IO can be generated from a proposal that is Ready (6) and has campaignGeneratable set to true. IQM names the proposed campaigns from the strategy's split, for example Campaign_Creative_Video_Device_mobile_Channel_App.

Generate an IO and campaigns​

Turn the proposal into an IO and draft campaigns.

PromptResponse exampleNotes
Generate an IO and campaigns from that proposal. Use the Political Advertiser profile in this Workspace and the proposal's current start time. Leave out the end time so the duration is kept.MCP finds the Political Advertiser profile in the Workspace. If there's more than one, name the profile to use. This step can't be undone: it creates a real IO and draft campaigns. The proposal becomes Converted (1), its ioId is set, and campaignGeneratable becomes false.

Voter TV+ proposals​

Voter TV+ (objective 3) plans forecast reach across linear TV and CTV. A Voter TV+ plan must have a flight of 7 to 31 days and a budget of at least 100, and can't target Power Segment audiences.

Get a reach saturation graph​

Forecast reach for the plan's budget and targeting before you create it.

PromptResponse exampleNotes
I want to build a Voter TV+ (cross-screen) Political plan. Get a reach saturation graph with these settings:
  • Name: Voter TV+ Plan
  • Objective: Voter TV+ (objectiveId 3)
  • Total budget: $100,000
  • Flight: November 3, 2026 to November 16, 2026, US/Eastern (timezone 29), converted to epoch milliseconds
  • Frequency cap: 3
  • Targeting: state of California (30200005)
Use the default overview values. Show me the graphId, the overview values, and the audience overlap numbers: population, total reach, linear TV reach, CTV reach, overlap, and CTV incremental reach.
Nothing is saved in this step. The first graph request calls an external data service and can take more than 60 seconds. The response's graphId and overview values are needed to create the plan.
Recalculate the same graph with the same graphId, but change the linear TV share to 30% so 70% of the budget goes to CTV. Compare the new audience overlap numbers with the previous ones.Sending the graphId with new overview values recalculates the forecast. Change the linear TV share, CPMs, GRP, or CTV frequency to compare budget splits before you create the plan.

Create and activate a Voter TV+ plan​

Create the plan from the graph, then activate it into a proposal.

PromptResponse exampleNotes
Create a ready plan from that graph. Use the same name, objective (3), budget, flight dates, frequency cap, and targeting as the graph request, plus the graphId and the overview values from the graph you just calculated. Show me the request body and the planId that comes back.The plan uses the overview values from the last graph you calculated. Use the same targeting as the graph request so the plan matches its forecast. Voter TV+ plans always target video on CTV devices, so IQM replaces any device or creative targeting you send.
Voter TV+ plans don't generate strategies, so activate the plan directly: activate a proposal using the planId. Then get the proposal's details and list the proposed campaigns, showing which are linear TV and which are CTV, with their budgets, CPM, and targeted impressions. Confirm the status is Ready (6).The proposal has one linear TV and one CTV proposed campaign. The proposal's budget, reach, and impressions cover only the CTV share. The linear TV share is in the linearTvBudget, linearTvReach, and linearTvImpressions fields.

Split the CTV campaigns​

Split the proposal's CTV campaign into one campaign per location (optional).

PromptResponse exampleNotes
Add the following counties to target and then split this proposal's CTV campaigns into one campaign per county: Mendocino, Shasta, San Francisco, Los Angeles, Monterey, Orange, San DiegoTo change the targeting, MCP recalculates the graph for the counties, updates the plan, and activates a new proposal from it. The counties replace the state, so the plan targets only these counties. MCP then splits the new proposal's CTV campaign into one campaign per county, named <plan name>_Video + Loc_1 and so on, with the CTV budget divided between them. The linear TV campaign doesn't change.

Generate a Voter TV+ IO​

Turn the split proposal into an IO and draft campaigns.

PromptResponse exampleNotes
Generate an IO and campaigns from this proposal. Use the same Political Advertiser profile as before and the proposal's current start time, and leave out the end time. Then check the proposal again. Has it moved to Converted (1), and what is the ioId? Only the CTV proposed campaigns should have become campaigns, so confirm that no linear TV campaigns were created.Only the CTV proposed campaigns become draft campaigns. The linear TV proposed campaign stays on the proposal but isn't created in the IO. As with other Political proposals, this step can't be undone.

Tools index​

The table below lists the tools that MCP uses in this tutorial, with links to their API documentation. For every Planner API tool available in MCP, see the Planner API section of the Tools index.

Tool nameDescriptionDocumentation
createReadyPlanCreate a Political plan in ready statusCreate plan
getPlanDetailsByIdGet the details of a Political plan by IDGet plan details by ID
editPlanUpdate a Political planEdit plan
getPoliticalStrategyListingGet the list of strategies generated for a planGet list of strategies
activateProposalActivate a strategy, or a Voter TV+ plan, into a proposalActivate proposal
getProposalDetailsById_1Get the details of a Political proposal by IDGet proposal details
getAdvertiserProfilesGet the list of Advertiser profiles in a WorkspaceGet list of Advertiser profiles and details
generateIOCampaigns_1Generate an IO and draft campaigns from a Political proposalGenerate IO and campaigns
getCrossScreenGraphGet a reach saturation graph for a Voter TV+ planGet reach saturation graph
splitProposalSplit a Voter TV+ proposal's CTV campaigns by targeting typeSplit proposal
Have a question?
Was this page helpful?