Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.experio.cloud/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Integrations allow users to connect their own external accounts (e.g., Google Workspace) to Experio, giving AI assistants access to their email, calendar, files, and documents during conversations. As an administrator, you need to configure the OAuth credentials and enable the required Google APIs before users can connect.

​
Prerequisites

  • A Google Cloud project with billing enabled
  • Access to the Google Cloud Console
  • Admin access to Experio’s System Settings

​
Step 1: Create OAuth Credentials

1

Open Google Cloud Console

Go to APIs & Services > Credentials in your Google Cloud project.
2

Create OAuth Client ID

Click Create Credentials > OAuth 2.0 Client ID.
  • Application type: Web application
  • Name: Experio Google Workspace Integration
  • Authorized redirect URIs: Add your Experio callback URL:
https://your-domain/api/mcp/connections/google/callback
For local development, also add:
http://localhost:8000/api/mcp/connections/google/callback
3

Copy credentials

After creation, copy the Client ID and Client Secret. You will need these in Step 3.
If you have not configured an OAuth consent screen yet, Google will prompt you to do so before creating credentials. Set the consent screen to Internal (for Google Workspace organizations) or External (for testing), and add the scopes listed in Step 2.

​
Step 2: Enable Required Google APIs

In your Google Cloud project, go to APIs & Services > Library and enable each of the following APIs individually:
APIPurposeTools that require it
Gmail APIRead and search email messageslistGmailMessages, readGmailMessage, searchGmail
Google Drive APIList, search, and download filessearchDrive, listGoogleSheets, downloadFromDrive
Google Calendar APIRead calendar eventslistCalendarEvents, getCalendarEvent
Google Docs APIRead document contentreadGoogleDoc
Google Sheets APIRead spreadsheet datagetSpreadsheetInfo, readSpreadsheetRange
Each API must be enabled separately — even if the OAuth scope is granted, the tool will fail with “Permission denied” or “invalid_request” if the corresponding API is not enabled in the Google Cloud project. This is a Google Cloud requirement, not an Experio limitation.
To enable an API:
  1. Go to APIs & Services > Library
  2. Search for the API name (e.g., “Gmail API”)
  3. Click on the API and press Enable
  4. Repeat for each API in the table above

​
Step 3: Configure in Experio

Navigate to Admin > Settings > System Settings and set the following values:
SettingCategoryDescription
GOOGLE_MCP_CLIENT_IDAUTHThe OAuth Client ID from Step 1
GOOGLE_MCP_CLIENT_SECRETAUTHThe OAuth Client Secret from Step 1 (stored encrypted)
Navigate to Admin > Settings > System Settings, filter by the AUTH category, and set both values. Once saved, the integration is available to all users.
These credentials are shared across all users. Each user authenticates with their own Google account through the OAuth flow, but the OAuth application (Client ID/Secret) is configured once by the administrator.

​
Step 4: Test the Integration

  1. Log in as a regular user
  2. Navigate to Integrations from the sidebar
  3. Click Connect on the Google Workspace card
  4. Complete the Google sign-in flow
  5. Open a conversation and send a test message such as “List my recent emails”
  6. Verify that the assistant retrieves data from the connected Google account

​
How It Works

When a user connects their Google account:
  1. Experio redirects the user to Google’s OAuth consent screen
  2. The user grants read-only access to the requested services
  3. Experio stores the encrypted OAuth tokens in the UserMCPConnection model
  4. During chat, the Deep Agent’s router detects queries about Gmail, Drive, Calendar, or Docs
  5. The agent routes to a dedicated MCP retrieval phase that uses the user’s tokens to call Google APIs
  6. Results are included in the agent’s response with appropriate context

​
Agent Routing

The Deep Agent has an mcp_action routing path specifically for external service queries. When a user asks about their emails, calendar, or files, the router directs the query to this path instead of the standard knowledge base retrieval pipeline. If the user has not connected their account, the agent responds with guidance directing them to the Integrations page.

​
Troubleshooting

IssueResolution
Users see “Connect” but the OAuth flow failsVerify the redirect URI matches exactly, including the protocol (http vs https)
“Access blocked: Missing required parameter: client_id”The GOOGLE_MCP_CLIENT_ID setting is empty or not configured. Set it in Admin > Settings > System Settings
”Access blocked” error during OAuthCheck that the OAuth consent screen is configured and the required APIs are enabled
”Permission denied for spreadsheet/doc”The corresponding Google API (Sheets API, Docs API) is not enabled in the Cloud project. See Step 2
searchDrive returns “invalid_request”Google Drive API is not enabled, or the OAuth token was created before the API was enabled. Enable the API and have the user reconnect
”duplicate key” error on reconnectThis is handled automatically — Experio cleans up stale connections during OAuth callback
Agent does not use Google dataEnsure the assistant uses Deep Agent mode — other agent modes do not support MCP integrations
Agent says “I can’t access your Gmail” despite tools succeedingStart a new chat — the previous conversation may have stale state from before the connection was established
Tokens expire or stop workingUsers can disconnect and reconnect from the Integrations page to refresh tokens