Product knowledge
Docs
Copilot Studio integration
Connect a Copilot Studio agent to Raptor Insights with a personal Gateway token, preserve the Insights endpoint and test the real Qlik connection.
On this page
Before you start
Start with an installed, activated Gateway and a working Qlik connection. This procedure connects a personal Gateway token to Copilot Studio. The test prompts below use Qlik Sense Enterprise on Windows; use your platform’s discovered tools for Qlik Cloud.
Ask your administrator for the exact Insights MCP URL and personal access-page URL. Microsoft’s cloud services must be able to reach the HTTPS endpoint and trust its certificate. Keep any non-standard port in the URL. A managed certificate trusted only on the Gateway computer does not establish Microsoft-side trust.
Have permission to create an agent, connector and connection in the intended Power Platform environment, with the required Microsoft entitlement. The Gateway administrator must assign your named user an appropriate seat, Insights access and Qlik identity through Raptor Administration > Seats. Sign in at the Gateway access page and obtain your personal token.
The example hostname and port are placeholders. Use the exact values supplied for your installation. Your Portal licence token, Qlik API key and Qlik password are not connector credentials.
Server URL: https://gateway.example.com:7443/mcp?domain=insights
Authentication: API key
Type: Header
Header name: Authorization
Credential value: Bearer <gateway-user-token>1. Create the agent and connection
Use the same Power Platform environment in Copilot Studio and Power Apps. Raptor Insights, Raptor Insights Token and Your name - Raptor Insights below are suggested display names you choose, not preinstalled Microsoft connectors.
- In Copilot Studio, create a standard agent and name it Raptor Insights.
- Open Tools > Add a tool > New tool > Model Context Protocol. Enter Raptor Insights Token as the server name, a short Qlik analytics description and your complete Insights MCP URL.
- Choose API key, then Header, and set the header name to Authorization. Create the server definition.
- Create a new connection, give it a personal display name and enter Bearer followed by a space and your Gateway user token in the secure credential field. Save the connection and add the server to the agent.
2. Check the saved host and Insights domain
Open the connector in Power Apps > Custom connectors > Edit. If it is not visible in navigation, look under More > Discover all > Data. Under General, check HTTPS, the exact hostname and port, and the base URL, normally /. Save the connector and wait for its update to finish.
The request must retain domain=insights. Under Definition, open the MCP operation. A wizard-created connector can call it InvokeServer; an imported Gateway definition can use a different operation name. Inspect the Request and its query parameters. If domain is missing, use Import from sample with POST and the complete Insights URL, leaving sample Headers and Body blank. Edit an existing parameter rather than adding a duplicate.
- Set the domain query parameter’s default value to insights, make it required and set its visibility to Internal.
- Under Policies, add a Set query string parameter policy, for example InsightsDomain. Set parameter name domain, value insights and the existing-parameter action to override. Leave Operations empty to apply it to every operation.
- Update the connector, return to Copilot Studio and refresh it. Reload the agent editor if necessary to refresh tool discovery.
- For the OpenAPI import route, the Gateway supplies /copilot-mcp.insights.user-token.openapi.yaml. Import the definition from your own Gateway and verify its saved host, port and domain. The definition identifies the MCP operation with x-ms-agentic-protocol: mcp-streamable-1.0.
- Use Streamable HTTP. The older standalone MCP SSE transport is not the Copilot Studio connection path. Qlik Python SSE is a separate analytics feature.
3. Review the tools and orchestration
Check the discovered tools before saving. App-building tools such as generate_app, set_script and publish_app must be absent from this Insights connection. If they appear, correct the saved domain and refresh discovery before continuing.
Allow all applies to the tools exposed by this endpoint. It can include bookmarks, schedules and delivery actions permitted to the user; it does not make the agent strictly read-only. Select the tool scope appropriate for your audience.
Under Settings > Generative AI > Orchestration, confirm generative orchestration is enabled. Review any Microsoft terms and data-handling notice for your environment. Leave additional options such as web search, file uploads, code interpreter and deep reasoning off unless the use case needs them.
Add the instructions below under Overview > Instructions. Save, then start a new test conversation.
Instructions for an Insights agent
These instructions retain the customer guide’s discovery, credential and evidence rules. They allow requested selections and bookmarks while keeping app building outside this agent’s scope. Gateway and Qlik authorization remain the enforcement layer.
Use the configured Raptor Insights MCP server for Qlik work.
Before Qlik analysis, reporting or governance work, use search_raptor_skills or get_raptor_task_playbook for relevant Raptor guidance. Use search_qlik_tools to discover the live tools needed. Do not invent tools, apps, fields or results.
Identify the intended Qlik platform and app. Inspect the app and use its actual fields, charts and current selection context. Prefer read-only calls. State the expression, result, selections and period used for a business answer; distinguish a partial period from a completed period.
This agent is for Insights. Do not create or modify apps, sheets, visualizations, scripts, data connections, master items, extensions or themes. Do not reload or publish apps. If a request needs Builder tools, explain the limit and direct the user to their Builder client.
User-requested selections and bookmark creation, application or deletion are allowed through the discovered Insights tools and the user's Qlik permissions. Schedules, delivery and other state-changing Insights actions require user authorization and the tool's own confirmation contract. Do not substitute arbitrary execution for an unavailable action.
Never ask for Qlik keys, certificates or passwords in chat. Never display Gateway tokens or Qlik credentials. The Gateway resolves the user's configured Qlik identity internally. If access is blocked, report the permission or connection issue without claiming the action succeeded.
Verify results with live Qlik inspection or the relevant status tools. Report what was checked, any authorized action taken and anything still unresolved.4. Test the connection and one real app
Run the first prompt in a new test conversation. For the second prompt, use an app name and ID returned by the first result. Prefer a published app you can also open in Qlik.
Test the live Insights connection: call test_connection, then list up to five published Qlik Sense apps accessible to me. Report the real connection result and app names and IDs. Use read-only calls only.Using the Raptor Insights tools, inspect the available fields in YOUR_APP_NAME (app ID YOUR_APP_ID). Evaluate one simple count using an actual field from that app. Report the exact expression, result and selections. Use read-only calls and do not build or modify app content.- Inspect the execution trace: the connection test, app listing, field inspection and expression evaluation must have completed against the intended platform.
- Compare the chosen app, expression, result and selections with Qlik. A plausible answer without a successful tool trace is not a connection test.
- Before sharing, test the published channel as an intended end user. Confirm which connection and Qlik identity actually run the tools; a maker-provided connection can execute as the maker rather than the person chatting.
5. Publish and maintain the integration
Resolve the agent’s errors and relevant entitlement warnings, publish it and wait for Published status. For Teams or Microsoft 365, configure the channel and intended audience, then test there. Force newest version can interrupt existing conversations and reset their state; use it deliberately when replacing a live version.
If a new Gateway token still produces an authentication error, recreate the affected Power Platform connection with the new credential. Editing the connector definition does not necessarily replace a saved connection credential. Revoke the old token through the Gateway after the replacement is verified.
For wrong or missing tools, check the saved host, port, Insights domain, seat, role, licence and Qlik access. For reachability failures, check Microsoft-side network access and TLS trust. Refresh connector discovery after changes.
This procedure uses a personal Gateway token. Native Gateway OAuth is optional and requires compatible client support and explicit administrator configuration. Entra OAuth/OBO is a separate mode with verified Microsoft-to-seat identity mapping; it is not enabled simply by choosing OAuth in Copilot Studio. Do not replace this working token connection with an unverified OAuth configuration.
Related guides
Reference documentation
Previous
Connect an AI client
Next