The MCP shim for desktop AI clients#

Desktop and IDE AI clients such as Claude Desktop, Cursor, and Cline speak MCP over a launched local process, while Reportworq serves MCP over HTTP. The MCP shim (reportworq-mcp.exe) is the small Windows connector that bridges the two: the client launches it, and it forwards the client's requests to Reportworq. Through the shim, the client sees the same governed report catalog and the same permission trimming as any other MCP client.

When to use it. Use the shim for a local AI client that launches an MCP server as a process on a Windows workstation. Native-HTTP clients such as ChatGPT and Copilot Studio need no connector, they connect directly over HTTPS, so for those the admin recipe gives you a URL-only snippet instead. Microsoft 365 Copilot uses the Copilot agent, not the shim.

Before you begin#

• You are a Reportworq administrator to download the connector and generate the snippet; the resulting snippet and .exe are then handed to the integration user who runs the client.
• Decide the connection path:
  • Direct on-prem needs a workspace Local API access token and Enable Local API on.
  • CloudHub-relayed needs a registered CloudHub connection and its connector key. See Copilot, MCP, and trust paths.
• The workstation runs Windows x64. The v1 connector is Windows x64 only.

Download the connector and snippet (administrator)#

1. Open Settings ▸ AI Agent Access (MCP).
2. Expand the Connect: MCP clients (Claude Desktop, Cursor, ChatGPT, Copilot Studio) recipe.
3. Choose Download Connector to stream the bundled reportworq-mcp.exe.
4. Pick your Client and Connection Path. The recipe generates a copy-paste configuration snippet shaped for that client and path. Only the paths your channel switches allow are offered.
5. Hand the connector and the snippet to the integration user.

The connector also ships inside the main Reportworq installer, one copy per installed version. To update the binary on a workstation, re-download the current version from this recipe.

Configure the client (integration user)#

1. Place reportworq-mcp.exe somewhere on the workstation. Putting it on PATH is simplest; it needs no separate .NET runtime.

2. Paste the snippet into your AI client's mcpServers configuration block. The snippet's arguments differ by connection path:

   Argument	Direct on-prem	CloudHub-relayed
   --server	Your Reportworq URL	The CloudHub base URL
   --apikey	Your workspace Local API access token	Omitted (the relay injects the workspace token)
   --path	Not used	/mcp/v1/<cloudhub-connector-key>
   ?workspace=<name>	Not used	Appended to --path when more than one workspace exists; omitted for a single workspace

3. Restart the AI client so it launches the connector.

Test the connection and download readiness#

Confirm the shim is wired before relying on it in the client, because a client that cannot reach Reportworq often shows a confusing "server crashed" or "no tools available" message rather than a clean transport error.

1. From a terminal, run the connector with your arguments and pipe an MCP initialize request to it. A single JSON-RPC line comes back with a server name of reportworq-mcp, which confirms the connector is framing correctly.
2. Follow with a tools/list request. A tool list confirms the upstream Reportworq instance is reachable and your credentials were accepted.
3. In the client, ask what reports are available. You should see the catalog trimmed to your permissions.

Notes and limits#

• Windows x64 only in v1. There is no macOS or Linux build, and no standalone installer, the connector ships inside the main Reportworq installer.
• API-key path, no per-user identity. The shim authenticates with an API key, so it runs in the full-workspace System scope. Secured-list and folder trimming still apply, but there is no per-user identity on this path. For an identity-scoped, per-user experience, use a native-HTTP OAuth client or the Copilot agent.
• The direct path needs Enable Local API on. With it off, the direct path is refused (as is a disabled Direct URL channel). The CloudHub path is gated separately by the relay channel and Cloud Connector.

Going deeper. For the two ingress models the shim can target and how each is gated, see Copilot, MCP, and trust paths. Shim tool calls are recorded with a client and transport value; see MCP audit.