Copilot Studio - Primr MCP Integration¶
Create a Copilot Studio agent that uses Primr's research tools via a Power Platform custom connector. This enables conversational company research directly in Microsoft 365 Copilot, Teams, and other Power Platform surfaces.
Primr is CLI-first, local-first. This guide is for teams that have deployed Primr to Azure Container Apps and want to connect it to Copilot Studio. If you haven't deployed yet, start with the Azure Quickstart.
Prerequisites¶
- Primr deployed to Azure Container Apps (Azure Quickstart)
- Access to Copilot Studio
- Power Platform environment with custom connector permissions
- The OpenAPI spec at
deploy/azure/openapi.yaml
How It Works¶
Copilot Studio connects to Primr via a Power Platform custom connector created from the OpenAPI spec. The spec includes the x-ms-agentic-protocol: mcp-streamable-1.0 extension, which tells Copilot Studio that this endpoint speaks MCP - enabling automatic tool discovery.
Step 1: Prepare the OpenAPI Spec¶
- Copy
deploy/azure/openapi.yamlto your local machine - Edit the server URL to match your deployment:
Replace {primr-fqdn} with your Container App's FQDN (e.g., primr-myteam-api.eastus.azurecontainerapps.io).
- If using Entra ID auth (organization tier), update the security scheme:
securitySchemes:
entraId:
type: oauth2
flows:
authorizationCode:
authorizationUrl: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize
tokenUrl: https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
scopes:
"api://{app-id}/.default": Access Primr MCP Server
Replace {tenant-id} with your Azure AD tenant ID and {app-id} with your Container App's Entra ID application ID.
Step 2: Create the Power Platform Custom Connector¶
- Go to Power Platform Admin Center or Power Automate
- Navigate to Custom connectors → + New custom connector → Import an OpenAPI file
- Upload your edited
openapi.yaml - On the General tab:
- Connector name:
Primr MCP - Host:
{primr-fqdn} - Base URL:
/ - On the Security tab, configure authentication:
API Key Auth (Team Tier)¶
- Authentication type: API Key
- Parameter label: Authorization
- Parameter name: Authorization
- Parameter location: Header
- Default value:
Bearer {your-api-key}
OAuth 2.0 (Organization Tier)¶
- Authentication type: OAuth 2.0
- Identity provider: Azure Active Directory
- Client ID:
{app-id} - Client secret: (from your Entra ID app registration)
- Authorization URL:
https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/authorize - Token URL:
https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token -
Scope:
api://{app-id}/.default -
On the Definition tab, verify the
mcpRequestaction is listed - Click Create connector
- On the Test tab, create a connection and test with:
You should see the list of Primr tools in the response.
Step 3: Create a Copilot Studio Agent¶
- Go to Copilot Studio
- Click + Create → New agent
- Name it (e.g., "Company Research Assistant")
- In the agent configuration, go to Actions → + Add an action
- Search for your
Primr MCPcustom connector - Select the
mcpRequestaction - Copilot Studio will detect the
x-ms-agentic-protocol: mcp-streamable-1.0extension and enable MCP tool discovery automatically
Step 4: Configure Agent Instructions¶
In the agent's Instructions field, add guidance for research workflows:
You are a company research assistant powered by Primr. You help users research companies
by gathering public information, analyzing it, and producing strategic analysis.
When a user asks you to research a company:
1. Ask for the company name and website URL if not provided
2. Call estimate_run to show the expected cost and duration
3. Wait for the user to confirm before proceeding
4. Call research_company to submit the research job
5. Use check_jobs to monitor progress - research takes 35-50 minutes
6. When complete, use MCP `resources/read` for
`primr://output/artifacts/by_job/{job_id}` if your connector exposes
resource reads. If QA artifacts are attached, read
`primr://output/qa_summary/by_job/{job_id}` for compact QA metadata. Read
`primr://output/usage_summary/by_job/{job_id}` when the user needs cost,
timing, approval, or artifact-count metadata. Read
`primr://output/source_summary/by_job/{job_id}` when the user needs
citation/source appendix metadata. Read
`primr://output/trace_summary/by_job/{job_id}` when the user needs scrape
trace health metadata. Read
`primr://output/verification_summary/by_job/{job_id}` when the user needs
claim verification trust and count metadata without raw claims, source
URLs, search queries, explanations, or report body content. Read
`primr://output/calibration_summary/by_job/{job_id}` when the user needs
label-calibration counts, inference source-copy counts, or judge-agreement
metadata without raw claims, source URLs, evidence reviews, rationales, or
report body content. Request
report content only when the user needs a summary or downstream action
7. Treat MCP resource reads as audited operations: Primr records normalized
resource kind, hashed URI, hashed result body, job id when present, granted
scopes, duration, and outcome without raw URI query values or resource
bodies.
8. Share the key findings with the user
Important:
- Always return the live estimate before submitting a job (the common Standard
guidepost is about $1.26, but provider configuration and history can raise it)
- Research jobs are asynchronous; Standard commonly takes 34-53 minutes and
Premium can take 74-132 minutes
- Use show_usage to check the user's remaining budget
- Use doctor to diagnose any connectivity issues
Available research modes:
- scrape: Site corpus plus provider-synthesized insights (~2-5 min, ~$0.10)
- deep: Deep Research dossier plus sequential section expansion and the
default AI Strategy (~32-62 min, current static plan ~$5.38)
- full: Standard report plus the default AI Strategy (~34-53 min, common
xAI-plus-Gemini guidepost ~$1.26)
- premium: Structured evidence plus dossier, sequential expansion, and the
default AI Strategy (~74-132 min, current static plan ~$6.71)
Step 5: Test with Sample Queries¶
In the Copilot Studio test panel, try these queries:
Cost estimation¶
Expected: The agent calls estimate_run and returns cost/duration.
Submit research¶
Expected: The agent estimates, confirms, submits, and monitors the job.
Check status¶
Expected: The agent calls check_jobs with the job ID.
Budget check¶
Expected: The agent calls show_usage and returns the spending summary.
Diagnostics¶
Expected: The agent calls doctor and reports system status.
Troubleshooting¶
| Issue | Solution |
|---|---|
| Connector creation fails | Verify the OpenAPI spec is valid: use the Swagger Editor to validate |
| MCP tools not discovered | Ensure x-ms-agentic-protocol: mcp-streamable-1.0 is in the spec's operation extension |
| Authentication errors | For API key: verify the key is valid. For OAuth: check tenant ID, app ID, and client secret |
| Agent can't invoke tools | Test the connector directly in Power Automate first to isolate the issue |
| Timeout on tool calls | Research jobs are async (35-50 min). The agent should use check_jobs to poll, not wait for a synchronous response |
Reference¶
- OpenAPI spec:
deploy/azure/openapi.yaml - Bicep templates:
deploy/azure/bicep/ - Deploy script:
deploy/azure/deploy.sh - Azure Quickstart - Deploy Primr to Azure
- Foundry Agent Guide - Alternative: connect via Foundry Agent Service
- Copilot Cowork Guide - Publish this agent to M365 Agent Store