Overview
Integrations let each user connect their own external accounts to Experio. Connected services are
available in Deep Agent chat via the MCP retrieval path (mcp_action).
As an administrator you configure OAuth credentials once in System Settings. Each user completes
OAuth on the Integrations page.
| Integration | Admin configures | User connects |
|---|
| Google Workspace | Google Cloud OAuth client + APIs | Gmail, Drive, Calendar, Docs |
| Slack | Slack app OAuth client | Workspace messages and channels |
Prerequisites
- Admin access to Admin > Settings > System Settings
- Provider admin access (Google Cloud Console and/or Slack API)
- Your Experio backend URL (
BACKEND_URL), e.g. https://your-domain or http://localhost:8000
OAuth redirect URLs always follow:
{BACKEND_URL}/api/mcp/connections/{provider}/callback
{provider} with google or slack. The URL must match exactly (protocol, host, port).
Google Workspace
1. Create OAuth credentials
Open Google Cloud Console
Create OAuth client
Create Credentials → OAuth 2.0 Client ID → Web application.Authorized redirect URIs:https://your-domain/api/mcp/connections/google/callback
http://localhost:8000/api/mcp/connections/google/callback
Configure the OAuth consent screen first. Add the scopes from step 2 before users connect.
2. Enable Google APIs
Enable each API in APIs & Services > Library:
| API | Used for |
|---|
| Gmail API | Email read/search |
| Google Drive API | Files and search |
| Google Calendar API | Events |
| Google Docs API | Documents |
| Google Sheets API | Spreadsheets |
3. Experio settings
| Setting | Category |
|---|
GOOGLE_MCP_CLIENT_ID | AUTH |
GOOGLE_MCP_CLIENT_SECRET | AUTH |
4. Test
User: Integrations → Connect on Google Workspace → chat: “List my recent emails”.
Slack
Experio uses Slack user OAuth (token type xoxp). Add scopes under User Token Scopes, not
bot scopes. Posting messages still requires per-action approval in chat.
1. Create Slack app
Create app
At api.slack.com/apps, choose Create New App → From scratch.
Name the app (e.g. Experio) and select a development workspace. Redirect URLs
Open OAuth & Permissions → Redirect URLs. Add:https://your-domain/api/mcp/connections/slack/callback
http://localhost:8000/api/mcp/connections/slack/callback
User token scopes
Under Scopes → User Token Scopes, add:| Scope | Purpose |
|---|
channels:history, channels:read | Public channels |
groups:history, groups:read | Private channels |
im:history, im:read | DMs |
mpim:history, mpim:read | Group DMs |
users:read, users:read.email | User identity |
search:read | Message search |
chat:write | Post messages (optional; requires chat approval) |
chat:write for read-only search and history. Copy credentials
Settings → Basic Information → App Credentials. Copy Client ID and
Client Secret.
2. Experio settings
| Setting | Category |
|---|
SLACK_MCP_CLIENT_ID | AUTH |
SLACK_MCP_CLIENT_SECRET | AUTH |
npm run config:seed so these keys appear in System Settings. Ensure the
Slack MCP server is enabled in admin (seeded by migration).
3. Test
User: Integrations → Connect on Slack → chat: “Search Slack for messages about launch”.
How it works
- User starts OAuth from Integrations; Experio stores encrypted tokens on
UserMCPConnection.
- The Deep Agent router sends external-service questions to
mcp_action → MCP retrieval.
- MCP tools run with that user’s credentials (Google session home directory or Slack
xoxp token).
- Write tools (e.g. Slack post) trigger an in-chat approval step before execution.
If the user has not connected a service, the agent directs them to Integrations.
Troubleshooting
Google
| Issue | Resolution |
|---|
| OAuth fails immediately | Redirect URI must match exactly in Google Cloud |
Missing client_id | Set GOOGLE_MCP_CLIENT_ID in System Settings |
| Permission denied on a tool | Enable the matching Google API; user reconnects |
| Agent ignores Google data | Use Deep Agent; start a new chat after connecting |
Slack
| Issue | Resolution |
|---|
redirect_uri did not match | Add the exact callback URL under Slack Redirect URLs |
invalid_scope | Add the scope under User Token Scopes; user reconnects |
| Connect works but no Slack tools | Enable Slack MCP server; confirm Pass 3 migration applied |
| Search works, post fails | Add chat:write in Slack app; user reconnects |
