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:
- An account on the IQM platform
- See Before you begin to create an account and request a Client ID and Client Secret.
- IQM MCP connected to your AI assistant
- See MCP getting started.
- Access to a Political Workspace
- Political Planner requests from a Workspace outside the Political vertical are rejected.
- A Political Advertiser profile
- Required to generate an IO. See Get list of Advertiser profiles and details.
About the Political Planner
The Political Planner builds a forecast-backed media plan for a political campaign. A proposal goes through these steps:
- Create a plan
- Compare strategies
- Activate a proposal
- Generate the IO and campaigns
Voter TV+ plans start from a reach saturation graph instead, and are activated without a strategy:
- Get a reach saturation graph
- Create a plan
- Activate a proposal
- Split the CTV campaigns (optional)
- Generate the IO and campaigns
More resources
- Political Planner tutorial
- Planner API guidelines
- Political Planner overview Help Center article
Select a Political Workspace
Select the Organization to build the proposal in before you start.
| Prompt | Response example | Notes |
|---|---|---|
| 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.
| Prompt | Response example | Notes |
|---|---|---|
| We'll use SDK Test Customer. Create a ready Political plan with these settings:
| 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.
| Prompt | Response example | Notes |
|---|---|---|
| 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.
| Prompt | Response example | Notes |
|---|---|---|
I want to build a Voter TV+ (cross-screen) Political plan. Get a reach saturation graph with these settings:
| 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.
| Prompt | Response example | Notes |
|---|---|---|
| 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).
| Prompt | Response example | Notes |
|---|---|---|
| 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 Diego | To 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.
| Prompt | Response example | Notes |
|---|---|---|
| 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 name | Description | Documentation |
|---|---|---|
createReadyPlan | Create a Political plan in ready status | Create plan |
getPlanDetailsById | Get the details of a Political plan by ID | Get plan details by ID |
editPlan | Update a Political plan | Edit plan |
getPoliticalStrategyListing | Get the list of strategies generated for a plan | Get list of strategies |
activateProposal | Activate a strategy, or a Voter TV+ plan, into a proposal | Activate proposal |
getProposalDetailsById_1 | Get the details of a Political proposal by ID | Get proposal details |
getAdvertiserProfiles | Get the list of Advertiser profiles in a Workspace | Get list of Advertiser profiles and details |
generateIOCampaigns_1 | Generate an IO and draft campaigns from a Political proposal | Generate IO and campaigns |
getCrossScreenGraph | Get a reach saturation graph for a Voter TV+ plan | Get reach saturation graph |
splitProposal | Split a Voter TV+ proposal's CTV campaigns by targeting type | Split proposal |