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

# Custom integration

> Connect your own MCP server so the Dema Agent can use its tools.

## Overview

A custom integration connects the Dema Agent to an MCP (Model Context Protocol) server that you host or subscribe to. Once it is connected, the tools that server exposes appear alongside the built-in integrations and the agent can use them in conversations and scheduled runs.

Use a custom integration when the service you need is not in the [integrations list](/guides/agent/integrations/overview) and it already offers a remote MCP server.

<Warning>
  A custom integration gives the agent tools written by whoever runs that server, including the tool descriptions the agent reads. Only add servers you trust, and give the agent a token with the least access it needs.
</Warning>

***

## Prerequisites

* A remote MCP server reachable on the public internet over HTTPS. Both Streamable HTTP and SSE are supported: a URL ending in `/sse` connects over SSE, anything else over Streamable HTTP.
* Whatever the server needs to authenticate you: an access token, OAuth sign-in, or nothing at all.

***

## Add a custom integration

1. In Dema, go to **Agents → Settings → Integrations** (or, for an agent you created, **Configuration → Integrations**).
2. Click **Add integration**. **Custom Integration** sits at the top of the list, above the integrations enabled for your team.
3. Click **Connect** to open **Add custom integration**.
4. Fill in the form:

| Field              | Notes                                                                           |
| ------------------ | ------------------------------------------------------------------------------- |
| **Name**           | How the connection is labelled in Dema, for example `My App`.                   |
| **Description**    | Optional. A short reminder of what the server does.                             |
| **MCP server URL** | The server's HTTPS endpoint, for example `https://your-server.example.com/mcp`. |
| **Authentication** | **None**, **API Key**, or **OAuth**. See below.                                 |

5. Tick **I understand custom integrations can introduce risks**.
6. Click **Add**. With **None** or **API Key** the connection is created immediately. With **OAuth** you are redirected to your server to sign in, and the connection becomes active when you land back in Dema.

<Tip>
  You can add several custom integrations. Each server URL becomes its own connection, and its tools are listed under that connection's own name.
</Tip>

***

## Authentication options

| Option      | When to use it                                                                                                                                   | What Dema stores                          |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
| **None**    | The server needs no credentials, or it authenticates by URL alone.                                                                               | Nothing beyond the URL.                   |
| **API Key** | The server accepts a long-lived token. Dema sends it as `Authorization: Bearer <token>`.                                                         | The token, encrypted.                     |
| **OAuth**   | The server speaks OAuth, as most managed MCP servers do. Dema discovers the server's authorization endpoints and registers itself automatically. | The access and refresh tokens, encrypted. |

For **OAuth**, leave **Client ID** and **Client secret** empty unless your server cannot register clients automatically and gave you credentials to use. A client secret requires a client ID.

***

## Tools and approvals

Every tool from a custom integration **requires your approval before it runs**, whatever the server claims about the tool being read-only. When the agent wants to use one, it asks first and shows you the call.

To change that for an agent you created, go to **Configuration → Tool permissions** and auto-approve the individual tools you are comfortable with. See [Your agents](/guides/agent/your-agents#tool-permissions).

***

## Manage a custom integration

* **Edit** the name and description at any time from the integration card.
* **Reconnect** to change the server URL or the authentication method. For an OAuth connection those fields are locked while editing, because the token your server issued is bound to that server — use **Reconnect** instead.
* **Disconnect** removes the connection and its stored credentials from Dema. Also revoke the token or OAuth client at your server if it should stop working entirely.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Dema says the MCP server URL is not allowed">
    The URL must be HTTPS and its host must resolve to a public address. A
    server on your own network, behind a VPN, or on `localhost` cannot be
    reached by the agent — publish it, or put it behind a public HTTPS
    endpoint.
  </Accordion>

  <Accordion title="Dema says the server is already available as a built-in integration">
    Connect that integration from the integrations list instead. Ask an admin to
    enable it for your organisation if it is not available to you yet.
  </Accordion>

  <Accordion title="The agent does not see any tools from my server">
    Dema lists the server's tools when the agent runs. If the server is
    unreachable, rejects the credentials, or returns no tools, that integration
    is skipped for the rest of the conversation and the agent reports the error
    when it tries to use one of its tools. Check the connection status on the
    integration card, then reconnect with a fresh credential.
  </Accordion>

  <Accordion title="Reconnecting an OAuth connection asks for a client secret">
    That happens when you supplied client credentials yourself. Enter the client
    secret again, or clear the **Client ID** so Dema registers a new client with
    your server.
  </Accordion>
</AccordionGroup>

If you are still stuck, contact [support](mailto:info@dema.ai) with the server URL and the error message you see.