> ## 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.

# Integrations

> Configure per-user OAuth integrations (Google Workspace, Slack) for external tools in chat

## 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 |

Organization-wide connectors (e.g. HubSpot) are configured under **Admin > MCP > Organization
integrations**, not on this page.

## Prerequisites

* Admin access to **Admin > Settings > System Settings**
* Provider admin access (Google Cloud Console and/or [Slack API](https://api.slack.com/apps))
* 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
```

Replace `{provider}` with `google` or `slack`. The URL must match exactly (protocol, host, port).

***

## Google Workspace

### 1. Create OAuth credentials

<Steps>
  <Step title="Open Google Cloud Console">
    Go to [APIs & Services > Credentials](https://console.cloud.google.com/apis/credentials).
  </Step>

  <Step title="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
    ```

    Copy the **Client ID** and **Client Secret**.
  </Step>
</Steps>

<Warning>
  Configure the OAuth consent screen first. Add the scopes from step 2 before users connect.
</Warning>

### 2. Enable Google APIs

Enable each API in [APIs & Services > Library](https://console.cloud.google.com/apis/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

<Steps>
  <Step title="Create app">
    At [api.slack.com/apps](https://api.slack.com/apps), choose **Create New App** → **From scratch**.
    Name the app (e.g. Experio) and select a development workspace.
  </Step>

  <Step title="Redirect URLs">
    Open **OAuth & Permissions** → **Redirect URLs**. Add:

    ```
    https://your-domain/api/mcp/connections/slack/callback
    http://localhost:8000/api/mcp/connections/slack/callback
    ```

    Save URLs.
  </Step>

  <Step title="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) |

    Omit `chat:write` for read-only search and history.
  </Step>

  <Step title="Copy credentials">
    **Settings** → **Basic Information** → **App Credentials**. Copy **Client ID** and
    **Client Secret**.
  </Step>
</Steps>

### 2. Experio settings

| Setting                   | Category |
| ------------------------- | -------- |
| `SLACK_MCP_CLIENT_ID`     | AUTH     |
| `SLACK_MCP_CLIENT_SECRET` | AUTH     |

On new deployments, run `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

1. User starts OAuth from **Integrations**; Experio stores encrypted tokens on `UserMCPConnection`.
2. The Deep Agent router sends external-service questions to `mcp_action` → MCP retrieval.
3. MCP tools run with that user's credentials (Google session home directory or Slack `xoxp` token).
4. 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             |