Frequently Asked Questions

You'll need to decide on three things during onboarding:

1. OAuth Client: Use your own internal client ID and client secret, or use the central/shared one. If you're in a corporate Google Workspace environment, an internal client ID is recommended — certain workspace-specific features like Google Chat spaces require your own app.
2. Access Model: Choose between an allowlist model (only specific email addresses can sign in) or open access to all addresses.
3. Endpoint: You can get a custom subdomain (e.g., yourcompany.workspacemcp.com) or use the standard endpoint.

Student is for one learner who wants a safe, managed foundation for learning AI and agentic tool use. It uses the shared endpoint with allowlist-only access for a single Google account.

Standard is the fastest path. It uses the shared Workspace MCP Cloud endpoint with allowlist-only access and requires no custom OAuth setup on your side.

Custom is for teams that want more control. You can use a branded subdomain, keep the central Workspace MCP client on a custom endpoint, or bring your own Google Cloud client ID. If you bring your own client ID, it runs on a custom endpoint rather than the shared one.

Enterprise Unlimited is the white-glove option for dedicated deployment, onboarding help, or running the service in your own environment.

If you're not sure, start with Student for individual learning or Standard for a team. You can move to Custom later if you need your own client ID or a branded endpoint.

Student, Standard, and any setup using the central Workspace MCP client ID are allowlist-only. Add or update users through the onboarding form or by replying to your welcome email.

If you bring your own Google Cloud client ID, Workspace MCP stops managing the allowlist for you. Access is then controlled from your Google Cloud OAuth consent screen, where you can keep it restricted or open it more broadly.

Either way, each person signs in with their own Google account and only sees data they already have permission to access in Google Workspace.

You must use "Web Application" type. This is the single most common mistake new users make. The Desktop application type is only appropriate for local/self-hosted instances where you're running it directly in Claude Code via stdio. Because Workspace MCP Cloud is a hosted remote server, it requires the Web Application client type.

If you accidentally created a Desktop type client, you'll need to recreate it as Web Application and resubmit your credentials.

For a hosted Workspace MCP Cloud deployment, configure your Google Cloud Web Application client like this:

• Authorized JavaScript Origins: https://yoursubdomain.workspacemcp.com
• Authorized Redirect URIs: https://yoursubdomain.workspacemcp.com/oauth2callback

Replace yoursubdomain with your actual subdomain. If you are also testing a browser client locally, you can add http://localhost:8000 as an additional JavaScript origin. The example below shows that dual setup.

Navigate to: Google Auth Platform > Clients > (your Client ID)

The Authorized JavaScript Origins and Authorized Redirect URIs fields are on this page. Note: These fields only appear for "Web Application" client types, not Desktop types.

Run this command in your terminal:

claude mcp add --transport http workspace https://yoursubdomain.workspacemcp.com/mcp

After running the command, use /mcp in Claude Code to trigger the authentication flow. You'll be redirected to sign in with your Google account.

Tip: If you get a paste formatting error, make sure you're copying the command cleanly without any hidden formatting characters. Type or paste it fresh.

Use Claude's custom connector flow. This works for Claude Desktop and Claude on the web, including Claude cowork and scheduled tasks wherever custom connectors are available.

1. Open Connectors in Claude
2. Choose Add custom connector
3. Name it Workspace MCP and enter the MCP address from your welcome email, such as https://yoursubdomain.workspacemcp.com/mcp
4. Click Add, then complete the login flow

You do not need to edit claude_desktop_config.json for this hosted cloud setup.

Option 1 — Deeplink (Recommended): An "Add to Cursor" deeplink can be provided that installs it automatically. After clicking it, the server will show "needs authentication" — click "Connect" and sign in with Google.

Option 2 — Manual mcp.json config: Add the following to your Cursor mcp.json file:

{
  "mcpServers": {
    "workspace": {
      "url": "https://yoursubdomain.workspacemcp.com/mcp"
    }
  }
}

Important: Make sure Cursor is updated to the latest version. Older versions may not display the MCP settings pane at all.

Install VS Code from Microsoft's download page (macOS, Windows, and Linux). VS Code's agent mode supports MCP with Streamable HTTP and OAuth 2.1 (plus OAuth 2.0 IdPs).

You can add the server in several ways:

• Open the MCP gallery in the Extensions view (@mcp) and use MCP: Add Server
• Edit .vscode/mcp.json or your user mcp.json directly
• Use the CLI: code --add-mcp

For a remote HTTP server, add a config block like:

{
  "servers": {
    "workspace": {
      "type": "http",
      "url": "https://yoursubdomain.workspacemcp.com/mcp"
    }
  }
}

Install Windsurf for macOS, Windows, or Linux. Windsurf supports stdio, Streamable HTTP, and SSE transports, with OAuth support for each.

To add the server:

• Marketplace: Open the MCP Marketplace from Cascade and click Install
• Manual: Edit ~/.codeium/windsurf/mcp_config.json and add your server using serverUrl or url

1. Open Admin Settings → External Tools
2. Click + (Add Server)
3. Set Type to MCP (Streamable HTTP)
4. Enter your Server URL: https://yoursubdomain.workspacemcp.com/mcp
5. Set Auth type to OAuth 2.1
6. Save. If prompted, restart Open WebUI.

This is almost always a paste formatting issue. When copying the command from an email or web page, invisible formatting characters can get included. Try:

1. Type the command manually instead of pasting
2. Paste into a plain-text editor first, then re-copy
3. Use this exact string: claude mcp add --transport http workspace https://yoursubdomain.workspacemcp.com/mcp

This means your OAuth client is not configured with the correct redirect URIs. To fix:

1. Open your OAuth Client ID in Google Cloud Platform Console
2. Confirm you're using the Web Application client type (not Desktop)
3. Set Authorized JavaScript Origins to: https://yoursubdomain.workspacemcp.com
4. Set Authorized Redirect URIs to: https://yoursubdomain.workspacemcp.com/oauth2callback
5. Save and try again

If you used the Desktop client type, you'll need to recreate it as Web Application since Desktop clients don't have the redirect URI fields.

This is expected. We generally recommend keeping your OAuth app in testing mode unless you have a specific reason to make it publicly facing. Testing mode is fully functional — the only difference is the consent screen warning.

• The app works fine, but shows a warning screen during sign-in
• You may need to click "Advanced" and "Go to (app) (unsafe)" to proceed
• Verified public OAuth is only available when using the central client ID with no allowlist
• If you need a verified public-facing app or your organization blocks unverified apps entirely, see Google App Verification below

The best path depends on your organization's security posture, but here are your options in order of what we typically recommend:

1. Provide your own client ID (recommended): Supply your own OAuth client ID and secret from your organization's GCP project. This is the strongest option for enterprise environments — your security team retains full ownership of the OAuth client, has access to Cloud Console audit logs, controls API rate limits and quotas, and can manage the app lifecycle through your existing governance processes. The app will be implicitly trusted within your domain since it lives in your own GCP organization. Client ID verification is included as part of the enterprise plan.
2. Use your own GCP project with a personal account: Create the GCP project with a personal account that has admin access, then add your company email to the project via IAM. This lets you use the OAuth client from within your organization without going through a full procurement process.
3. Use the Custom plan with your own client ID: If your organization blocks unverified apps or needs a stricter security posture, this is the right setup. It keeps OAuth, consent, and access control under your own Google Cloud project so your team has end-to-end control.

In theory, yes — any framework that supports MCP servers and OAuth logins should work. However, there are key considerations:

• The agent must be able to handle the Google OAuth login flow (including any browser-based consent screens)
• If MFA is enabled on the Google accounts, the agent needs to handle that as well, which can be complicated for autonomous operation
• Each agent connecting with a different workspace account needs that account on the allowlist

Cloud deployments run in stateless mode by default. Credentials and session tokens are held in memory for the duration of a request and are not written to disk.

Requests are proxied directly to Google's APIs with the authenticated user's token. File-based debug logging is disabled, and attachments are returned directly rather than saved to the filesystem in the default setup.

Client secrets submitted during onboarding are stored in an encrypted database only long enough to provision your instance, then purged.

If you need persistent sessions or disk-backed storage, encrypted disk and Valkey/Redis-backed modes are available on request. See the privacy page for the deeper architecture overview.

No setup work required on your end. Just:

• Add https://mcp.workspacemcp.com/mcp to your client
• Complete the Google sign-in flow

That's it — you're connected.

A one-time setup that gives you full ownership of your OAuth client and a dedicated endpoint. Once it's done, you don't touch it again.

1. Create a Web Application OAuth client in Google Cloud Platform
2. Enable required Google APIs (quick links in the GitHub README)
3. Set Authorized JavaScript Origins to https://yoursubdomain.workspacemcp.com
4. Set Authorized Redirect URIs to https://yoursubdomain.workspacemcp.com/oauth2callback
5. Submit your client ID and secret at https://workspacemcp.com/welcome
6. Wait for your subdomain and SSL certificate to be provisioned
7. Add the MCP server to your client and complete the Google sign-in flow

If you see a "testing" warning on the consent screen, this is normal — your app works fine in testing mode.