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

# Connect external tools with integrations

> Give RAUM AI live access to your business data. Connect REST APIs for order or billing lookups, or add MCP servers for real-time tool execution during ticket resolution.

Integrations allow RAUM AI to fetch live data and take actions in external systems during the Act step of the ticket-resolution pipeline. Without integrations, RAUM AI can only use information from the ticket itself, your procedures, and your help center articles. With integrations, it can look up an order status in Shopify, check inventory in your warehouse system, or verify a shipment with FedEx — before it writes the reply.

There are two types of integrations:

| Type               | What it does                                                                                                                                        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Connection** | Calls a single REST endpoint. Simpler to configure; best for standard CRUD operations on external systems.                                          |
| **MCP Connection** | Connects to a Model Context Protocol server that exposes multiple tools. Better for complex, stateful workflows or when you need a pre-built skill. |

## API connections

API connections let RAUM AI call any REST endpoint using credentials you provide. Common examples include order management, payment processing, shipping carriers, and CRM systems.

### Add an API connection

<Steps>
  <Step title="Open Connections">
    In the RAUM AI dashboard, click **Connections** in the left sidebar.
  </Step>

  <Step title="Click New connection">
    Click **New connection** and select **API Connection**.
  </Step>

  <Step title="Enter the connection details">
    Fill in the following fields:

    | Field              | Description                                                                                                 |
    | ------------------ | ----------------------------------------------------------------------------------------------------------- |
    | **Name**           | A descriptive label, e.g. `Shopify — order lookup`. The AI uses this name when deciding which tool to call. |
    | **Base URL**       | The full endpoint URL, e.g. `https://your-store.myshopify.com/admin/api/2024-01/orders/{id}.json`.          |
    | **HTTP method**    | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.                                                                 |
    | **Auth type**      | `Bearer token`, `API key header`, `Basic auth`, or `None`.                                                  |
    | **Credentials**    | The API key or token. Credentials are encrypted at rest.                                                    |
    | **Description**    | Plain-language description of what this connection returns. The AI reads this to decide when to call it.    |
    | **Example output** | A representative JSON response. Helps the AI parse and use the data correctly.                              |
  </Step>

  <Step title="Configure caching and approval">
    Set a **Cache TTL** (in seconds) to avoid redundant API calls. Enable **Safe to simulate** if this endpoint is read-only and can be called without customer impact. Enable **Auto-approve** to let the AI call it without requiring agent approval.
  </Step>

  <Step title="Save">
    Click **Save**. The connection becomes available to the Tool Executor immediately.
  </Step>
</Steps>

### Supported connection categories

<CardGroup cols={2}>
  <Card title="E-commerce" icon="shopping-cart">
    Shopify, WooCommerce, Magento — order lookups, return status, inventory checks.
  </Card>

  <Card title="Payments" icon="credit-card">
    Stripe, Braintree — charge lookups, subscription status, refund eligibility.
  </Card>

  <Card title="Shipping" icon="truck">
    FedEx, UPS, USPS — tracking lookups, delivery estimates, carrier status.
  </Card>

  <Card title="CRM" icon="address-book">
    Salesforce, HubSpot — contact records, account health, deal status.
  </Card>
</CardGroup>

## MCP connections

MCP connections use the [Model Context Protocol](https://modelcontextprotocol.io) to connect RAUM AI to a server that exposes one or more tools. MCP servers communicate over SSE (Server-Sent Events), making them suitable for real-time data retrieval.

### Built-in skill types

When you add an MCP connection, you assign it a skill type. The type helps RAUM AI understand the category of data the server provides:

| Skill type             | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `WEATHER`              | Real-time weather conditions and forecasts                       |
| `PRODUCT_AVAILABILITY` | Stock levels, availability, and inventory status                 |
| `SERVICE_STATUS`       | System health, uptime, and incident status                       |
| `WEB_SCRAPER`          | Live content extraction from web pages                           |
| `CUSTOM`               | Any other tool — describe its purpose in the connection metadata |

### Add an MCP connection

<Steps>
  <Step title="Open Connections">
    Click **Connections** in the dashboard sidebar, then click **New connection** and select **MCP Connection**.
  </Step>

  <Step title="Enter the server URL">
    Paste the SSE endpoint URL of your MCP server. The URL must use HTTPS in production.
  </Step>

  <Step title="Select the skill type">
    Choose the skill type that best describes the server's capabilities. For servers that don't fit a standard category, choose `CUSTOM` and write a clear description.
  </Step>

  <Step title="Add credentials (if required)">
    If your MCP server requires authentication, enter the API key or headers. Credentials are encrypted with AES-256-GCM before storage.
  </Step>

  <Step title="Configure per-tool cache TTL">
    After the server connects, RAUM AI retrieves the list of tools it exposes. For each tool, set a **Cache TTL** in seconds. A higher TTL reduces API calls for data that doesn't change frequently (e.g., product catalog). Use `0` for data that must always be fresh (e.g., live order status).
  </Step>

  <Step title="Mark tools as safe">
    Tools marked as **Safe** are simulation-safe — they can run without agent approval because they are read-only and have no side effects. Mark any tool that only retrieves data and never modifies it.
  </Step>

  <Step title="Configure auto-approval">
    Tools with **Auto-approve** enabled run without requiring an agent to review the action in Copilot Mode. Enable this for low-risk lookups where human review would slow down resolution.
  </Step>

  <Step title="Save">
    Click **Save**. RAUM AI registers the server and its tools. The Planner and Tool Executor agents can now call these tools when resolving tickets.
  </Step>
</Steps>

## How RAUM AI uses integrations

During the Act step of the pipeline, the Tool Executor agent calls the relevant connections based on what the Planner Agent has determined it needs. Here is how a typical ticket flow works with integrations:

<Steps>
  <Step title="Thinker identifies data requirements">
    The Thinker Agent analyzes the ticket and determines which external data sources must be queried before a resolution is possible — for example, "This is a delivery inquiry, so order status and tracking must be fetched."
  </Step>

  <Step title="Tool Executor calls the connections">
    The Tool Executor calls your configured connections (or MCP tools) in the correct sequence. Results are cached using the TTL you configured to avoid redundant calls on subsequent tickets.
  </Step>

  <Step title="Planner decides based on live data">
    The Planner Agent combines the ticket context, your procedures, and the real-time data returned by the tools to determine the correct resolution: approve a refund, send a tracking link, escalate to a specialist, or another action.
  </Step>

  <Step title="Answerer writes the reply">
    The Answerer Agent generates the customer-facing reply using the resolution decision and your guidelines, then posts it to the Zendesk ticket.
  </Step>
</Steps>

### Example: order lookup

A customer submits a ticket: "My order #12345 was supposed to arrive yesterday. Where is it?"

1. The Thinker Agent identifies this as a delivery inquiry and flags the order lookup and shipping tracker connections as required.
2. The Tool Executor calls your **Shopify — order lookup** connection with order ID `12345`.
3. The Tool Executor calls your **FedEx tracking** connection with the tracking number from the order.
4. FedEx returns a status: "Out for delivery — estimated arrival today by 8pm."
5. The Planner Agent matches the delay procedure and determines no escalation is needed.
6. The Answerer Agent drafts a reply citing the tracking status and estimated delivery time.

<Tip>
  Write descriptive **Name** and **Description** fields for every connection. RAUM AI reads these fields to decide which tool to call. A connection named `API 1` with no description will rarely be selected correctly.
</Tip>