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 catalog of distribution jobs 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. When the instance uses OAuth access, Claude, VS Code, Cursor, and Cline connect without the shim and each user signs in; see Connect native MCP clients with OAuth sign-in (direct). 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. The shim is offered only under API Key access; under OAuth access, connect clients directly with sign-in instead.
  • 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 ▸ Integrations ▸ AI Agent Access (MCP).
2. Expand the Connect: MCP clients (Claude, VS Code, Cursor, Cline, 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 CloudHub connection itself carries authentication)
   --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 jobs are available. You should see the catalog trimmed to your permissions.

Connect native MCP clients with OAuth sign-in (direct)#

Claude (claude.ai and Claude Desktop), VS Code with GitHub Copilot, Cursor, and Cline can connect straight to the Reportworq /mcp endpoint with no shim and no API key. Each user signs in with your organization's own identity provider, and every result is scoped to that user's Reportworq permissions. The client finds your sign-in page from the server's protected-resource metadata, which names the MCP server URL you set up below. For how this works, a workflow diagram, and a short setup checklist, start with Direct OAuth sign-in for MCP clients; this section is the full per-client reference.

Prerequisites for direct sign-in#

Confirm the following before you start:

• AI Agent Access uses the OAuth access mode, with the Direct URL channel on.
• An OIDC single sign-on provider is active under Authentication: Microsoft Entra ID, or a custom OIDC provider such as Okta or Keycloak whose access tokens are JWTs with a configurable audience. Google sign-in can't be used for direct sign-in: Google's access tokens aren't JWTs and can't carry your server's URL as their audience.
• The identity provider holds your own app registration for Reportworq. An instance that uses the shared Reportworq multi-tenant Entra application cannot use direct sign-in (see Limits of direct sign-in).
• The /mcp endpoint has a public https address that the clients can reach, at the root of its host (https://reports.contoso.com/mcp, not https://apps.contoso.com/reportworq/mcp). With Microsoft Entra, its host must be a custom domain verified in your tenant (an *.azurewebsites.net host can't be used).
• For Claude, which connects from Anthropic's cloud: the address must resolve to a public IPv4 address (a split-horizon DNS answer that returns a private address fails), must not redirect to another host, and any firewall in front of it must admit Anthropic's outbound range 160.79.104.0/21.
• Every user who signs in has a Reportworq account that matches their identity-provider sign-in. The MCP path never creates accounts.

Set up direct sign-in (administrator)#

To advertise direct sign-in to the clients:

1. Open Settings ▸ Integrations ▸ AI Agent Access (MCP).
2. Under Access, set Access Mode to OAuth. Under Channels, turn on Direct URL. The Direct OAuth sign-in section appears. If this instance doesn't use CloudHub, also turn off CloudHub relay: while it is on with no Cloud API configured, the page refuses to save and asks for a Cloud API URL and key.
3. MCP server URL is the public https address of the /mcp endpoint exactly as the clients will use it, for example https://reports.contoso.com/mcp. When your External URL (under Settings ▸ Configuration) is an https address with no path, the page offers it followed by /mcp: select the Use button under the field to fill it in. Reportworq only accepts sign-ins for a URL saved here, never for one it works out on its own, so enter it only once your app registration carries it (see the identity-provider steps below). To use another address, enter it. Write it the way clients normalize it: lowercase host, no :443, and no trailing slash, query, or fragment. Write a non-ASCII host name in its xn-- form. The page refuses any other form and suggests the right one. If you reach the admin page through a different public address, a second Use button offers that one.
4. Leave OAuth audience as it is if you use Microsoft 365 Copilot: it is the same value as the OAuth Audience on the Copilot recipe, Copilot's tokens are checked against it, and the page won't let you clear it while the CloudHub relay channel is on. Tokens issued for the MCP server URL are accepted in addition. If it is blank and your Entra API issues v2.0 access tokens, set it to api://<API client id>: a v2.0 token carries the API's client id as its audience, and this value covers that.
5. Client ID for native apps is the application (client) id that the AI clients sign in with (see the identity-provider steps below). With Microsoft Entra, leave it blank to use the client id of the app registration Reportworq's sign-in uses; the field shows it. Enter another id only if you registered a separate app for the AI clients. It is not a secret. The connection recipes fill it in.
6. Select Save Changes.

The status line under the section reads Direct sign-in advertised for your URL once the saved settings are complete. If it shows anything else, it names the missing piece.

Configure your identity provider#

The section Direct OAuth: identity provider checklist on the same page lists these steps with your URL filled in. A Reportworq administrator cannot make these changes from Reportworq: an identity-provider administrator makes them.

The clients use the following redirect URIs:

Microsoft Entra ID. One app registration can do everything: the one Reportworq's sign-in already uses (its SSO app). Use a separate API or client app only if your security policy asks for one. In the Microsoft Entra admin center:

1. On the SSO app registration (or your separate API app), open Expose an API. Add the MCP server URL as an additional Application ID URI, keeping any api:// URI that Copilot already uses. The URL's host must be a custom domain verified in your tenant.

2. On the same page, add a delegated scope named access_as_user. Clients request <MCP server URL>/access_as_user.

3. On the client app registration (usually the same SSO app), open Authentication and add the redirect URIs of the clients you use. Register Cursor, Cline and mcp-remote under the Mobile and desktop applications platform, with no secret. If the portal refuses the http://127.0.0.1 address, add it in the app's manifest under publicClient.redirectUris. For Claude, use one of two setups:

   • the Mobile and desktop applications platform with no secret, leaving the secret blank in Claude; or
   • the Web platform with a client secret that you enter in Claude.

   The Web platform without a secret fails (AADSTS7000218), and the Single-page application platform does not work, because Claude redeems the sign-in from Anthropic's cloud.

4. Under Expose an API ▸ Authorized client applications, add your client app's id if it is a separate app and, for VS Code, aebc6443-996d-45c2-90f0-388ff96faa56 (VS Code's Microsoft sign-in), both for the access_as_user scope.

5. Optional: on the client app, open API permissions, add access_as_user, and grant admin consent, so users aren't asked to consent when they first sign in.

Leave the SSO app's Web redirect and client secret as they are: Reportworq's own sign-in keeps using them. Adding the public-client redirects makes the SSO app usable from desktop apps without its secret. Reportworq still only accepts tokens issued to a signed-in user for its own audience, so this lets the AI clients sign users in and nothing more. If your security policy keeps confidential and public clients apart, register a separate app for the AI clients and enter its id in Client ID for native apps.

Other identity providers (Okta, Keycloak, other custom OIDC). Make the access tokens for this API carry the MCP server URL as their audience (in Okta, the authorization server's audience; in Keycloak, an audience mapper on the client). Register a public client app for the AI clients with the redirect URIs above, and enter its id as Client ID for native apps. Also check that:

• the access token carries the user's email and user id in the claims set for the SSO provider under Authentication (for example email and sub);
• users are allowed refresh tokens: the clients request offline_access so that users stay signed in, and a provider that refuses it fails the sign-in (in Keycloak, the user needs the offline_access role, which the realm's default roles include);
• each user has a Reportworq account for that SSO provider. Accounts, groups and roles are kept per provider, so a Native account with the same email address is not used.

The server can only advertise a scope for Microsoft Entra, so with another provider the clients choose the scope themselves; mcp-remote asks for every scope the provider lists. If your provider refuses some of them, pass the scope to use with --static-oauth-client-metadata and a file (@/path/to/metadata.json holding { "scope": "openid email profile offline_access" }), since that option takes no environment variable.

Connect each client (integration user)#

Expand Connect: MCP clients on the same page, pick the client, and keep the Direct connection type. The recipe carries the saved MCP server URL and client id and contains no API key. Then follow the steps for your client:

• Claude (claude.ai and Claude Desktop). Open Customize ▸ Connectors, choose + Add ▸ Add custom connector, paste the MCP server URL, and continue. Under OAuth client, choose Use your own OAuth client and enter the client id (in some layouts this field is under Advanced settings, labeled OAuth Client ID). Enter a client secret only if your registration is a Web app with one. Claude's other choices, its published identity and automatic registration, don't work with Microsoft Entra. Connect and sign in. On Team and Enterprise plans, members can't add custom connectors: an Owner adds it under Organization settings ▸ Connectors ▸ Add ▸ Custom ▸ Web, and members then select Connect. The Free plan allows one custom connector. Claude's sign-in settings can't be changed after the connector is added: to change them, remove the connector and add it again.
• Claude Desktop through its config file, or another MCP host that takes the same mcpServers JSON. Under the Claude recipe, the page also offers a config file snippet. Paste it under mcpServers in claude_desktop_config.json (or your host's equivalent) and restart the host. It runs the mcp-remote bridge, pinned to a tested version, through npx, so Node.js 18 or later must be installed. The first time it starts, it opens a browser for the user to sign in with the client id from the snippet, then keeps the tokens in ~/.mcp-auth and refreshes them. Register http://127.0.0.1:3334/oauth/callback on the client app as described above. The client id travels in the REPORTWORQ_MCP_CLIENT_INFO environment variable rather than in the arguments, because Claude Desktop on Windows passes the arguments to npx without escaping them. Signing in asks the user to consent each time a new sign-in starts (mcp-remote adds prompt=consent when it asks for a refresh token). This sign-in has been tested with Microsoft Entra, using the SSO app alone as API and client. In a Microsoft Entra tenant where users can't consent to apps, grant admin consent first (step 5 above); a user may still be asked for admin approval, which has not been tested. If Microsoft Entra answers AADSTS9010010, check that the MCP server URL is an Application ID URI of the API app (step 1); adding --disable-resource-parameter to the arguments is the fallback. Claude Code needs no bridge: add the MCP server URL with claude mcp add --transport http. Claude Code expands ${...} in a pasted config itself and won't load the server while the variable is unset.
• An MCP host that already holds the user's token (an agent harness of your own, for example). The page offers a second snippet that passes the host's token to the server through mcp-remote instead of signing in. Set REPORTWORQ_MCP_AUTHORIZATION to Bearer followed by the user's access token. The token must come from the identity provider Reportworq trusts, carry the MCP server URL (or the OAuth audience) as its audience and the user's email, and the host must renew it before it expires: once the server refuses it, mcp-remote tries to sign in on its own, which this snippet isn't set up for. In Claude Code, export the variable before starting it, for the same ${...} reason as above.
• A server-side agent whose users sign in to it with Microsoft Entra (your own enterprise assistant, for example). No snippet is needed: the agent calls the MCP server URL over Streamable HTTP and sends each user's own token as Authorization: Bearer. It gets that token with the on-behalf-of flow: it exchanges the token the user signed in to the agent with for one whose scope is <MCP server URL>/access_as_user. In Entra, give the agent's app registration the API permission access_as_user on the SSO app and grant admin consent, so no user is asked; adding the agent's client id under Authorized client applications with Who can consent set to Admins only keeps other apps out. Each user sees only what their Reportworq account can see. App roles assigned on the SSO app arrive in the token on every call, so Reportworq groups matched to those roles apply as they do in the portal. Every user needs a Reportworq account: signing in to Reportworq once creates it. The on-behalf-of call and the role scoping have been tested with Microsoft Entra.
• VS Code (GitHub Copilot). Paste the snippet into .vscode/mcp.json in your workspace, or run MCP: Open User Configuration. Start the server and sign in when VS Code asks. With an identity provider other than Microsoft Entra, VS Code asks for a client id; add "oauth": { "clientId": "..." } to the server entry to skip the prompt. That setting needs VS Code 1.116.0 or later; older versions ignore it.
• Cursor. Paste the snippet under mcpServers in ~/.cursor/mcp.json, enable the server, and sign in when Cursor asks. Leave scopes out of the auth block: Cursor then requests the scope the server advertises plus offline_access, which keeps users signed in. With an identity provider other than Microsoft Entra, the server can't advertise a scope, so add "scopes": [...] with the scope your provider issues for this API (and its refresh scope, if it has one).
• Cline. In VS Code, open the Cline extension, then MCP Servers ▸ Configure MCP Servers, and paste the snippet into cline_mcp_settings.json. Keep "type": "streamableHttp" spelled exactly so. Without it Cline falls back to an older transport and the connection fails with a 405 error. Any other value fails Cline's settings check, and Cline then loads none of its MCP servers. Signing in needs a recent Cline release.

To confirm the connection, ask the client which distribution jobs it can see. The list you get is trimmed to your own Reportworq permissions.

Limits of direct sign-in#

• Your own app registration only. Direct sign-in is not available when the instance uses the shared Reportworq multi-tenant Entra application, which is the default for the one-click Microsoft 365 Copilot setup. That application's Application ID URI belongs to Reportworq and can never match your server's URL, so the Direct OAuth sign-in fields are disabled. Switch the Copilot recipe to your own registration to use direct sign-in. Microsoft 365 Copilot works either way.
• Direct only, not through CloudHub. Claude, VS Code, Cursor, and Cline find their sign-in from the server, which the CloudHub relay doesn't pass through, so they must reach the /mcp endpoint directly under OAuth. Copilot Studio can still use the CloudHub relay under OAuth with its OAuth 2.0 ▸ Manual setting, and the Microsoft 365 Copilot agent keeps using CloudHub. ChatGPT is not offered under OAuth access.
• No shim and no key under OAuth. An OAuth instance refuses API keys, so the recipe does not offer the shim or a key-based snippet for these clients while OAuth is the access mode. Under API Key access, the shim and the key-based recipes work as described above.
• Not yet proven against every client release. The steps above follow each vendor's current documentation and source code (checked October 2026). Client sign-in screens change; if a step no longer matches, the server-side settings above still apply.

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, connect a client directly with OAuth sign-in or use 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, and works whether or not the Reportworq API / Local API keys are enabled for the workspace - turning the API off only affects direct, non-relayed API calls.

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.