Skip to main content

MCP Healthcare Professional (HCP) Planner tutorial

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

Overview​

This tutorial guides you through using IQM MCP to generate, save, edit, publish, and download an HCP plan with the Planner API. Publishing a plan creates an insertion order (IO) and draft campaigns.

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 HCP Planner, refer to the Healthcare Professional (HCP) Planner tutorial and the Planner API guidelines.

Before you begin​

To create and publish an HCP plan, 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 Healthcare Advertiser Organization
    • HCP Planner requests only work in the Healthcare vertical, and only Advertiser Organizations can publish plans.

About the HCP Planner​

The HCP Planner builds a media plan that targets healthcare professionals by National Provider Identifier (NPI) type, specialty, location, and data partner. A plan goes through these steps:

  1. Generate campaigns
  2. Save the plan
  3. Edit the plan (optional)
  4. Publish the IO and campaigns

More resources​

Select a Healthcare Workspace​

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

PromptResponse exampleNotes
I want to build a Healthcare Professional (HCP) plan with IQM's Planner. List the Organizations and Workspaces I can access and select my Healthcare Workspace.MCP lists the Organizations you can access and selects the Healthcare Advertiser. HCP Planner requests only work in the Healthcare vertical, and publishing requires an Advertiser Organization.

Generate and save a plan​

Generate the plan's proposed campaigns, save them as a ready plan, and check the saved plan.

PromptResponse exampleNotes
Generate the proposed campaigns for this plan. Show me the plan totals (min/max budget, impressions, and reach) and a table of the proposed campaigns with name, creative type, NPI type, media CPM, data CPM, budget, reach, and impressions. Keep the full response; we'll save it as the plan next.
  • Name: MCP HCP 02
  • Flight: November 1, 2026 to November 30, 2026, US/Eastern (timezoneId 29), converted to epoch milliseconds
  • Budget type: Budget
  • Frequency cap: 3 per day
  • NPI types: HCP and NPI nurse
  • One filter-based audience block: all specialties, United States with no state, city, or ZIP code filters, data partners 7 (priority 1) and 8 (priority 2), both selected
  • Plan-level targeting: creative types image and video, device types 20300001 and 20300004, TV auto buying off
  • Split strategy: by creative type and by NPI type
Nothing is saved in this step. MCP converts the flight to epoch milliseconds and returns one proposed campaign per creative type and NPI type. IQM names the campaigns from the split, for example Campaign_Video_HCP_Matched_Audience. The HCP Planner also needs channel and inventory targeting; when the prompt doesn't include them, MCP sends them as all selected.
Save this as a ready HCP plan, sending the full response from the generate step as the request body without changing the campaigns. Show me the plan ID that comes back.Ask MCP to send the generate response unchanged. Saving doesn't check that the plan totals match the campaigns, so a modified body is saved as sent. The returned ID is the plan ID for every later step.
Get the details of that plan. Show me its statusId (it should be Ready, 6), its ioId, and a summary of the saved campaigns.A saved plan is Ready (6), and its ioId is 0 until it's published. The details return minBudget and minImpressions as null and the inventory group as an empty object; MCP corrects these when it edits or publishes the plan.

Edit and publish the plan​

Update the saved plan, then publish it to create an IO and draft campaigns.

PromptResponse exampleNotes
Edit the plan to change the frequency cap to 5 per week.MCP sends the full plan back with its current statusId, adds back minBudget and minImpressions, and sets the inventory group to null. Every campaign uses the plan's frequency cap, so only the plan-level value needs to change.
Publish this plan to create an IO and campaigns.Publishing runs in the background and can take a few minutes. When it finishes, the plan is IO Created (7), and its ioId and each campaign's campaignId are set. The campaigns are created as drafts. Each save gives the plan's campaign records new IDs, so use each campaign's campaignId elsewhere in IQM.

Download the plan​

Download the plan as a spreadsheet or PDF to share.

PromptResponse exampleNotes
Download the plan as an Excel file (fileTypeId 1).HCP plans can be downloaded as Excel (1) or PDF (3) files. Use the Download button to save the file. If the Workspace selection has lapsed, MCP selects the Workspace again and retries.

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
generateHCPProposedCampaignsGenerate the proposed campaigns and totals for an HCP plan, without saving itGenerate campaigns plan
createProposal_1Save an HCP plan in ready statusCreate HCP Planner
addDraftProposal_1Save an HCP plan in draft statusCreate HCP Planner
getHcpPlanByIdGet the details of an HCP plan by IDHCP Planner details by ID
editProposal_1Update an HCP planUpdate HCP Planner
generateIOCampaigns_2Publish an HCP plan to create an IO and draft campaignsPublish campaigns plan
downloadPlanDownload an HCP plan as an Excel or PDF fileDownload HCP Planner
Have a question?
Was this page helpful?