Webinar: Better Agents, Easier than Ever — Thursday, June 18th at 9am PT / 12pm ET. Register Now
Version 2.5
First-time setup
Set up OAuth for MCPs

Set up OAuth for MCPs

Several servers in the Sema4.ai MCP Gallery act on behalf of a signed-in user and authenticate with OAuth 2.0:

  • Google Workspace — Gmail, Google Docs, Google Drive, Google Sheets, Google Calendar.
  • Microsoft 365 — Outlook Mail, Calendar, OneDrive, SharePoint, Teams, Excel.

Before your users can connect these, an admin must create an OAuth client in your own Google Cloud project, or an app registration in your own Microsoft Entra tenant, and enter the resulting Client ID and Client Secret into the MCP server's configuration in the application.

This applies only to the OAuth-based Google and Microsoft gallery MCPs. The vendor remote MCPs handle their own OAuth. The Sema4.ai MCP Gallery is deployed automatically with the application, so these servers are already available — you just need to set up their OAuth.

User-authenticated vs. workspace-level auth

MCP servers authenticate in one of two ways. Knowing which kind you're configuring tells you what to set up and what to expect.

  • User-authenticated — each end user signs in to their own account and consents the first time they use the server. The agent then acts on behalf of that specific user, and access respects that user's own permissions. The admin sets up the OAuth client once (the Client ID, Client Secret, and redirect URL on this page); every user still does their own sign-in. The Google Workspace and Microsoft 365 gallery MCPs work this way — they use the OAuth 2.0 authorization-code flow.
  • Workspace-level — a single shared credential is configured once and used by everyone in the workspace. There's no per-user sign-in; all agents and users act under the same identity and access. This covers MCPs that take an API key (for example a web-search server) or use an OAuth client-credentials / service identity.

The rest of this page covers user-authenticated setup — creating the OAuth client at Google or Microsoft so your users can connect their own accounts. Workspace-level MCPs are configured by entering their API key or service credentials directly when you add the server; they don't need the redirect-URL flow below.

How it works

The application provides the redirect URL (the OAuth callback); you create the OAuth client at the provider and bring back the Client ID and secret.

Step 1: Start adding the MCP server

In the application, go to Configuration > MCP Servers and add the gallery server you want (for example Google Docs or Microsoft Mail). The Add MCP Server dialog shows a Redirect URL field with a copy button.

Step 2: Copy the redirect URL

Copy the Redirect URL — for example https://<your-backend>/oauth/callback. You'll register this exact value at the provider.

Step 3: Create the OAuth client at the provider

Follow the Google or Microsoft instructions below to create the client, set the redirect URL, grant the scopes the MCP needs, and obtain a Client ID and Client Secret.

Step 4: Enter the credentials

Back in the Add MCP Server dialog, paste the Client ID and Client Secret and save. Use Edit full configuration if you need to adjust scopes or endpoints.

The redirect URL matters. It's shown in the Add MCP Server dialog and is specific to your deployment. It must be entered at the provider exactly as shown, or sign-in fails with a redirect-URI-mismatch error. The same redirect URL is used for every MCP in your deployment, so you can register it once per provider and reuse a single OAuth client across multiple MCPs (as long as it includes all the scopes those MCPs need), or create one client per MCP.

Google Workspace

Create an OAuth client in Google Cloud Console (opens in a new tab) (Google's guide: Setting up OAuth 2.0):

  1. In a Google Cloud project, enable the APIs for the MCPs you'll use — for example the Gmail API, Google Docs API, Google Drive API, Google Sheets API, or Google Calendar API.
  2. Configure the OAuth consent screen for your organization.
  3. Under Credentials, create an OAuth client ID of type Web application.
  4. Add the copied redirect URL as an Authorized redirect URI. It must use HTTPS.
  5. Copy the generated Client ID and Client Secret.

Each Google MCP declares the scopes it needs. For example, Google Docs requests documents, drive.readonly, and drive.file; Google Mail requests gmail.readonly, gmail.modify, and gmail.send. The exact scopes are visible under Edit full configuration in the Add MCP Server dialog.

Microsoft 365

Create an app registration in Microsoft Entra ID (opens in a new tab) (Microsoft's guide: Register an app):

  1. In the Microsoft Entra admin center, go to App registrations > New registration.
  2. Under Authentication, add a Web platform (opens in a new tab) and set its Redirect URI to the copied redirect URL.
  3. Under API permissions, add the Microsoft Graph delegated permissions the MCP needs — for example, Microsoft Mail uses Mail.ReadWrite, Mail.Send, User.Read, and offline_access.
  4. Under Certificates & secrets, create a New client secret and copy its value immediately (it's only shown once).
  5. Copy the Application (client) ID.

The Client ID is the Application (client) ID, and the Client Secret is the secret value (not its ID).

Reusing the application's Entra app. If your deployment already signs users in with Microsoft Entra, you can reuse that same app registration for the Microsoft MCPs — add this MCP redirect URL alongside the existing one and add the Microsoft Graph delegated permissions. A separate app registration is cleaner, though: it keeps the login app to least privilege, isolates secret rotation, and keeps consent and audit focused. (This only applies to Microsoft; Google MCPs always need their own Google Cloud OAuth client.)

Automated setup with Bicep

A Bicep template that provisions the Entra app registration for you — redirect URL, Graph permissions, and all — is coming soon. Walkthrough to follow.

Network egress

The OAuth flow and the subsequent API calls go out from your deployment to the provider. Allow outbound HTTPS (443) to:

ProviderEndpoints to allow
Googleaccounts.google.com, oauth2.googleapis.com, www.googleapis.com
Microsoftlogin.microsoftonline.com, graph.microsoft.com

In addition, the provider redirects the user's browser back to your redirect URL after consent, so that callback endpoint must be reachable from where your users sign in. See Add networking rules for more.

MCP serversSet up MCP orchestration