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:
- 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 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:
- Generate campaigns
- Save the plan
- Edit the plan (optional)
- Publish the IO and campaigns
More resources
- Healthcare Professional (HCP) Planner tutorial
- Planner API guidelines
- HCP Planner overview Help Center article
Select a Healthcare Workspace
Select the Organization to build the plan in before you start.
| Prompt | Response example | Notes |
|---|---|---|
| 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.
| Prompt | Response example | Notes |
|---|---|---|
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.
| 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.
| Prompt | Response example | Notes |
|---|---|---|
| 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.
| Prompt | Response example | Notes |
|---|---|---|
| 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 name | Description | Documentation |
|---|---|---|
generateHCPProposedCampaigns | Generate the proposed campaigns and totals for an HCP plan, without saving it | Generate campaigns plan |
createProposal_1 | Save an HCP plan in ready status | Create HCP Planner |
addDraftProposal_1 | Save an HCP plan in draft status | Create HCP Planner |
getHcpPlanById | Get the details of an HCP plan by ID | HCP Planner details by ID |
editProposal_1 | Update an HCP plan | Update HCP Planner |
generateIOCampaigns_2 | Publish an HCP plan to create an IO and draft campaigns | Publish campaigns plan |
downloadPlan | Download an HCP plan as an Excel or PDF file | Download HCP Planner |