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.

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.

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"
    }
  }
}

Download Claude Desktop for macOS or Windows. Claude Desktop and Claude on the web both support remote MCP servers with OAuth and Streamable HTTP.

To add Workspace MCP:

1. Open Customize > Connectors > Add custom connector
2. Enter a name and your server URL: https://yoursubdomain.workspacemcp.com/mcp
3. Optional advanced settings let you supply an OAuth client ID and secret

Important: Remote MCP servers must be added through Settings > Connectors, not by editing claude_desktop_config.json.

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. Wait for verification on the central client: If you're using the central client ID, Google verification takes 3–5 business days after submission. Once verified, the warning goes away and blocked organizations can use it. Note that verified public OAuth is only available for the central client ID with no allowlist.

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

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.