Direct OAuth sign-in for MCP clients#

With direct OAuth sign-in, an AI client connects straight to your Reportworq MCP server URL (for example https://reports.contoso.com/mcp) and acts as the person using it. That person signs in with your organization's own identity provider, and every answer is limited to what their Reportworq access allows. There is no API key to hand out, store, or rotate.

How it works#

1. The client discovers how to sign in. Its first call without a token gets a 401 that points to Reportworq's protected resource metadata at /.well-known/oauth-protected-resource/mcp. That document names the MCP server URL as the resource, your identity provider as the place to sign in, and, with Microsoft Entra ID, the scope to request: <MCP server URL>/access_as_user.
2. The user signs in with your identity provider, Microsoft Entra ID or another OIDC provider such as Okta or Keycloak. How depends on the client:
   • Interactive clients (Claude Desktop, Claude Code, claude.ai, VS Code, Cursor, Cline) open a browser and use the authorization code flow with PKCE.
   • A server-side agent that your users already sign in to calls on their behalf: it exchanges the user's token for one scoped to Reportworq (the Entra on-behalf-of flow), so the user never signs in twice.
3. The token is issued for your MCP server URL. Its audience is that URL, and Reportworq refuses any token whose signature, issuer, or audience doesn't match.
4. Reportworq maps the token to a person. The token's email and user id must match an existing Reportworq account. The MCP path never creates accounts, so each user must have signed in to Reportworq once (or been added by an administrator).
5. Roles decide what the agent can see. Entra app roles or group claims in the token map to Reportworq groups, exactly as they do when the person signs in to the portal. Tools and results are trimmed to that person's permissions, and each call is recorded under their name in the MCP audit.

Before you begin#

• An OIDC single sign-on provider is the active provider under Authentication (see Authentication providers), and it uses your own app registration, not the shared Reportworq multi-tenant Entra application. Google sign-in can't be used.
• The MCP endpoint has a public https address at the root of its host, such as https://reports.contoso.com/mcp. With Microsoft Entra ID, the host must be a domain verified in your tenant. For Claude, which connects from Anthropic's cloud, it must also be reachable from the internet.
• Three people usually share the work: a Reportworq administrator, an identity-provider (Entra) administrator, and whoever sets up the AI client or agent.

Set up Reportworq (Reportworq administrator)#

1. Open Settings ▸ Configuration. Under Web Server, set External URL to the public https address of the server with no path, for example https://reports.contoso.com, and save.

   

2. Open Settings ▸ Integrations ▸ AI Agent Access (MCP).

3. Under Access, set Access Mode to OAuth.

4. Under Channels, turn on Direct URL. Turn off CloudHub relay unless you also use Microsoft 365 Copilot through CloudHub: while the relay is on with no Cloud API configured, the page won't save. The Direct OAuth sign-in section appears.

5. Under MCP server URL, select Use https://reports.contoso.com/mcp (your External URL plus /mcp), or type the URL. Reportworq never fills this in on its own: it only accepts sign-ins for a URL an administrator has saved here.

   

6. Leave OAuth audience as it is. Leave Client ID for native apps blank to use your Entra sign-in app's client id (the field shows it), or enter the id of a separate app you registered for AI clients.

7. Select Save Changes. The status line reads Direct sign-in advertised for your URL.

   

   Any other status names the missing piece, for example an OIDC provider that isn't active yet.

The collapsible Direct OAuth: identity provider checklist below the section repeats the next steps with your URL filled in, so you can pass it to your Entra administrator.

Set up Microsoft Entra ID (Entra administrator)#

Work on the app registration Reportworq already signs in with (its SSO app). In the Microsoft Entra admin center:

1. Expose an API ▸ Application ID URI. Add the MCP server URL, for example https://reports.contoso.com/mcp, exactly as saved in Reportworq. Keep any api:// URI that is already there. The host must be a domain verified in your tenant.
2. Expose an API ▸ Add a scope. Add a delegated scope named access_as_user. Clients then request https://reports.contoso.com/mcp/access_as_user.
3. For interactive clients: under Authentication, add the redirect URIs of the clients you use, and for VS Code authorize its client id. The full list is in Configure your identity provider.
4. For a server-side agent: on the agent's own app registration, add the API permission access_as_user on the SSO app and grant admin consent, so no user is prompted. Optionally also add the agent's client id under Expose an API ▸ Authorized client applications.
5. Assign access. Under Enterprise applications for the SSO app, assign app roles or groups to the users, and map those roles or groups to Reportworq groups (see Authentication providers).

With another OIDC provider, make access tokens for this API carry the MCP server URL as their audience and register a public client for the AI clients; see Other identity providers.

Connect the client or agent#

• Interactive clients. In AI Agent Access (MCP), expand Connect: MCP clients, pick the client, and keep the Direct connection type. The recipe carries the MCP server URL and client id. Per-client steps are in Connect each client.

• A server-side agent. Call the MCP server URL over Streamable HTTP and send each user's own token as Authorization: Bearer <token>. Get that token with the Entra on-behalf-of request to https://login.microsoftonline.com/<tenant id>/oauth2/v2.0/token:

  Parameter	Value
  grant_type	urn:ietf:params:oauth:grant-type:jwt-bearer
  requested_token_use	on_behalf_of
  assertion	The token the user signed in to your agent with
  scope	https://reports.contoso.com/mcp/access_as_user
  client_id, client_secret	Your agent's app registration and its secret (or certificate)

  Renew the token before it expires; Reportworq refuses an expired one.

Check it works#

1. Open https://reports.contoso.com/.well-known/oauth-protected-resource/mcp in a browser. The resource value must be exactly your MCP server URL, and with Entra scopes_supported lists https://reports.contoso.com/mcp/access_as_user.
2. Connect a client as a test user and ask which distribution jobs it can see. The list should match what that user sees in the portal.

Troubleshooting#

Related pages#

• The MCP shim for desktop AI clients: per-client redirect URIs, connection steps, and limits of direct sign-in.
• Copilot, MCP, and trust paths: how direct and CloudHub-relayed access differ.
• MCP audit: what each agent call records.