Copilot, MCP, and trust paths#

This section is written for two audiences: administrators who expose Reportworq to AI clients and external systems and set the posture that governs them, and integration users who connect a client and consume the result. Read this overview first to place the pieces, then follow the task pages for the surface you are setting up.

The three integration surfaces#

Reportworq presents its report catalog and outputs to AI and automation in three ways. They are separate front doors onto the same governed content, and which one you choose depends on the client.

The first two, Copilot and MCP, share the same underlying MCP server and its tool surface, so an AI client sees the same catalog and the same permission trimming whichever it uses. The third is a distinct HTTP command surface for running and monitoring jobs, covered in the Automation API section.

MCP and Copilot are the same tools, different clients#

Reportworq serves the Model Context Protocol (MCP) from a single in-process server. Every AI client, whether Microsoft 365 Copilot or a desktop client behind the shim, calls the same read-and-act tools: list the report catalog, list a report's runs, fetch an output or its markdown, take a governed preview, and email an output. Access is trimmed by the same content-service ACLs and secured lists that govern the web UI, so an AI client is a new way to ask, not a new way to see. A user never reaches a report or output variation their Reportworq permissions do not allow.

Copilot reaches those tools with no client-side connector, over the CloudHub relay. Desktop clients that speak MCP over a launched process use the stdio shim. Native-HTTP clients (ChatGPT, Copilot Studio) connect directly over HTTPS with no connector at all.

The two trust paths#

Whichever surface a client uses, its request reaches the on-prem Reportworq instance by one of two trust paths. This is the central decision for an administrator, because it determines what the customer owns and what has to be opened.

Direct on-prem#

The customer exposes the MCP or API endpoint to callers through a customer-managed reverse proxy (for example NGINX, Caddy, or IIS ARR) at a public DNS name with a public-CA TLS certificate. Nothing about Reportworq brokers the traffic; the customer owns the DNS name, the certificate, the reverse-proxy configuration, and, for the identity path, outbound reachability to their identity provider.

Choose direct on-prem when a security posture forbids cloud relays, for example an air-gapped or strictly outbound-only deployment. Note that a self-signed certificate does not work for cloud-hosted callers such as Copilot Studio; the certificate must be public-CA (Let's Encrypt is fine). Reportworq does not generate the reverse-proxy configuration, so this path hands the DNS, TLS, and proxy plumbing to customer IT.

CloudHub-relayed (the recommended default)#

The on-prem instance registers with Reportworq CloudHub and holds an outbound connection to it. CloudHub forwards each request down that existing connection. There is no inbound firewall change and no public endpoint on the customer's server, the instance only ever dials out. This is the default, and it is what the Microsoft 365 Copilot agent uses.

Choose CloudHub-relayed for a fast rollout with no firewall change, and for any cloud-hosted caller.

Who reaches what: identity is the boundary#

The two trust paths are about how traffic arrives; a separate mechanism decides what a caller may see.

• Under the identity (OAuth) path, each request carries the signed-in user's identity. Reportworq resolves that identity to a Reportworq account and runs the request as that user, scoped to exactly the workspaces, folders, and reports that user's permissions allow. For the relayed Copilot agent, identity, not network location, is the security boundary: a token is honored only if it resolves to a real, enabled Reportworq user on the instance it reaches.
• Under the API-key path (used by the stdio shim and the relay's injected token), the request runs as the instance's System scope, full-workspace by design, optionally narrowed to a named workspace. There is no per-user identity on this path, but content-service trimming still applies.

Posture: turning surfaces on and off independently#

An administrator gates each ingress with an MCP-scoped channel switch, so the two paths can be enabled or disabled independently:

• The Direct URL channel governs direct callers, and enabling it also turns on the workspace's Local API.
• The CloudHub relay channel governs relayed callers, and enabling it also turns on the Cloud Connector.

An instance-wide access mode (Disabled, Key, or OAuth) sits above both. Because the channels are MCP-scoped, turning off the direct channel stops AI agents on that ingress without disabling the shared Local API or Cloud Connector features behind it. This is what lets an administrator, for example, lock down the direct API surface while a relayed Copilot agent keeps working.

Every request that reaches a tool, and every request rejected at the gate, is recorded. See MCP audit.

Going deeper. For the full trust-path model, the download-delivery rules for large outputs, and the per-ingress gating detail, this overview's companion pages carry the depth: start with Microsoft 365 Copilot agent and The MCP shim for desktop AI clients. For programmatic job execution, see The automation API.