> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osvi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> Connect third-party apps to your workspace so agents can act on them and journeys can react to their events

An integration is a third-party app your workspace connects to. Once it's connected, its actions can be turned into tools your voice and chat agents call, and — in a journey — its events can complete or cancel a journey.

<Note>
  Integrations isn't publicly released yet. Until it is, contact [support@osvi.ai](mailto:support@osvi.ai) to have it enabled for your workspace.
</Note>

Connecting an app doesn't put it in front of any agent by itself — you still choose which of its actions become tools, and which agents get them. See [Library tools](/platform/tools#library-tools) for that step.

## Connecting an integration

<Steps>
  <Step title="Open Add integration">
    On the **Integrations** page, click **Add integration** (or **Connect your first integration** if the list is empty). Browse or search the catalog. The **Show available** toggle limits the list to apps Osvi has ready to connect; turn it off to browse the full directory.
  </Step>

  <Step title="Pick an app">
    Click a card to open it. The dialog has **Configure**, **Tools**, and **About** tabs. **Tools** previews the app's available actions before you connect — it tells you to add them to agents from the Tools page once the app is connected.
  </Step>

  <Step title="Authorize the connection">
    On **Configure**:

    * Apps that support it show **Connect with OAuth**. This opens a popup to the app's own sign-in and authorization page. When it finishes, the popup shows *"Authorization complete — you can close this window."* and closes itself; the app's row shows **Connected**.
    * Apps that use an API key, token, or similar instead show the credential fields the app needs, with a **Connect** button. A note next to them explains that the credentials go straight into Osvi's secure connection storage and aren't kept anywhere else.
    * If your browser blocks the popup, Osvi shows a toast asking you to open the authorization page manually.
  </Step>
</Steps>

A connected app shows a green **Connected** badge in the Integrations list. If Osvi can't confirm connection status right now, the list shows a message that connected apps can't be listed at the moment, rather than guessing which ones are connected. Custom MCP servers aren't affected — they keep showing their own health badge.

## Custom MCP servers

You can also connect an MCP server you run yourself, instead of one of the catalog apps.

From **Add integration**, choose **Add a custom MCP server** to point Osvi at your own MCP endpoint. This opens a panel with:

| Field | Notes |
| - | - |
| **Name** | How the server appears in your integrations list. |
| **Server URL** | The MCP endpoint Osvi connects to. |
| **Transport** | **Streamable HTTP** or **SSE**. |
| **Timeout (s)** | 5–300 seconds; default 30. |
| **Secret token** | Optional. Sent as an `Authorization` bearer header. Write-only — once saved it shows as *"Unchanged — type to replace"* and is never shown again. |
| **Request headers** | Optional additional headers, as JSON. |

Save with **Add server**. Osvi connects to the server when your agents actually need it, not continuously — its row shows a live health badge: **Checking…**, **Reachable**, **Unreachable**, or **—** if the check itself couldn't be completed.

To change a server later, open its row and edit the same fields, or **Archive** it. Archiving a custom MCP server also archives any tools built from it, so no agent is left pointing at a tool that no longer resolves to anything.

## Disconnecting an integration

Open the app from the Integrations list, go to **Configure**, and click **Delete integration**. Osvi asks you to confirm:

> **Delete integration?**
> This disconnects it and may stop existing tools that use it.

Disconnecting removes the authorization, but it does **not** delete any tool you built from that app — tools stay attached to the agents that use them. The app's row instead switches to an amber **Needs attention** badge, and reopening it offers **Reconnect** (or **Reconnect with OAuth**) to restore the connection and keep those tools working.

<Warning>
  Disconnecting may stop existing tools built from that app from working, even though they stay attached to your agents. Reconnect the app to restore them.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="I can't find the app I want to connect">
    Turn off **Show available** in the Add integration dialog to search the full directory rather than only the curated list. The directory search needs at least 3 characters.
  </Accordion>

  <Accordion title="An app I connected shows Needs attention">
    The connection stopped working — reconnect it from the app's **Configure** tab. Tools built from it keep their settings; they just can't run until the connection is restored.
  </Accordion>

  <Accordion title="Could not load supported integrations">
    Close the dialog and try again, or turn off **Show available** to browse the full directory instead.
  </Accordion>

  <Accordion title="An MCP server shows Unreachable">
    Osvi couldn't reach the server's URL. Check that it's running and reachable from the internet, and that the timeout is long enough for it to respond.
  </Accordion>
</AccordionGroup>