---
title: "Create and manage MCP Connections"
description: "Create a named MCP Connection to make a remote server's Tools eligible for Agent Identities, then manage assignments, call policy, and access."
lang: en
status: public-preview
lastUpdated: 2026-10-18
url: https://dev.duale.ai/en/docs/tools/mcp-connections
---

## AI-generated summary

This guide covers prerequisites, creation and verification, identity sharing, and access control for MCP Connections.

- Prerequisites and permissions for creating a Connection.
- Creating, verifying, and assigning an MCP Connection.
- Remote identity and credential sharing across assigned Agent Identities.
- Changing, blocking, disabling, or deleting a Connection.

Summaries were generated by AI.

---

Create a named **MCP Connection** to make a remote server's current compatible Tools eligible for selected Agent
Identities. The Connection is reusable across your organization. Every assigned Agent Identity uses the same remote
access configured on that Connection.

> [!WARNING]
> When you assign a Connection, every compatible Tool that the server exposes now or later can become eligible. Duale AI
> offers no per-Tool selection and no approval prompt for MCP calls. Review the remote account's permissions and the
> complete catalog before you allow calls. If a person must approve an action, use the two-step proposal in [Secure
> integration](https://dev.duale.ai/en/docs/security/secure-integration.md).

## Before you create the Connection

You need:

- `config:read_config` and `config:create_config` on `config:*` to use the Dashboard creation flow,
  `tools:read_catalog` on `tenant:<tenant_id>` to inspect the observed catalog, and `agent:manage_tools` on each
  `agent:<agent_id>` you assign. Duale AI checks each permission for the signed-in person in the selected Tenant;
  [Identity](https://dev.duale.ai/en/docs/identity.md) owns that model.
- A sign-in at AAL2 for creation, editing, and assignment. Catalog inspection needs
  only AAL1.
- A public HTTPS MCP endpoint that uses Streamable HTTP and responds directly at the exact configured URL. Check the
  supported protocol versions and HTTP behavior in the [Tools
  reference](https://dev.duale.ai/en/docs/tools/reference.md#confirm-mcp-server-compatibility).
- Either unauthenticated access, one bearer token, or one API key sent in a custom header.
- The Agent Identities that will receive the complete compatible Tool set.

Use a test account with the least remote access needed for the first connection. Create separate named Connections when
the same MCP server must use different credentials, remote accounts, environments, or data. For example, use `CRM
Production` and `CRM Sandbox` instead of two indistinguishable names. A server whose catalog is larger than one
Connection accepts also needs splitting; [Tool limits](https://dev.duale.ai/en/docs/tools/limits.md#how-many-tools-one-source-can-publish)
states that ceiling.

## Create and verify the Connection

1. **Open Tools**

   In the Dashboard, select your Tenant, open **Tools**, keep the **Connections** view selected, then choose **Create
   Connection**.
2. **Describe the remote server**

   Enter a distinctive Connection name and its public HTTPS endpoint. The endpoint cannot contain user information,
   query parameters, or a fragment, and Duale AI does not follow a redirect to another URL.
3. **Choose remote authentication**

   Select **No authentication**, **Bearer token**, or **API key**. For an API key, enter a custom header name. Duale AI
   rejects headers reserved by HTTP, authentication, or MCP, including `Authorization`, `Cookie`, `Host`,
   `Content-Type`, and names beginning with `MCP-`. Saved secret values are not shown again. Replace a value to rotate
   it.
4. **Set availability and call policy**

   Keep the Connection enabled so Duale AI checks its catalog. Select **Allow calls** to make compatible Tools eligible
   after a successful check, or **Block calls** to observe the Connection without permitting new calls.
5. **Save and inspect the catalog**

   Save the Connection, then open its detail page. Expect **Not observed** until the first successful catalog check.
   Success changes the catalog to **Active**, and the **Tool catalog** section shows the Tools the server reported.
   Saving valid configuration alone does not prove that the server works.
6. **Assign Agent Identities**

   On the Connection detail page, choose **Manage assignments**, select up to 1,000 Agent Identities, then choose
   **Save assignments**. You can save assignments before the first successful catalog check. No Tool is offered from
   this Connection until Duale AI successfully reads its catalog. You can also open an Agent Identity in **Agent
   settings**, select **Tools**, and assign the Connection there.

After the catalog becomes active, run one low-risk test Task and confirm the expected result in the destination system.
That destination record verifies the individual call. Separately, use **Analytics** to review final outcomes aggregated
for the Connection and time window. The Connection detail page states the confirmed success rate and links to that view
with **View Connection Tool Analytics**. Analytics cannot identify the test call, and a catalog check lists Tools without
running them. [Operate Tools](https://dev.duale.ai/en/docs/tools/operations.md) explains catalog states, names, outcomes, and reliability. If
the catalog does not become **Active**, follow [Troubleshoot Tools](https://dev.duale.ai/en/docs/tools/troubleshooting.md).

## Know which identity reaches the server

The configured bearer token or API key identifies the remote account. All Agent Identities assigned to one Connection
share that account and its remote permissions. Duale AI sends neither the assigned Agent Identity nor the end-user
identity to the MCP server.

If the remote server varies its catalog or behavior by credential, create one Connection for each remote account and
permission set. Do not share a Connection across teams that require different remote authorization or attribution.

## Change or stop access

Editing the endpoint, authentication, name, assignment list, enabled state, or call policy starts a new check of the
current configuration. Editing the Connection requires `config:update_config` on `config:*`; changing an assignment
requires `agent:manage_tools` on that `agent:<agent_id>`. Deleting the Connection requires `config:delete_config` on
`config:*` and a sign-in at AAL3. Use these controls for different outcomes:

| Control                  | Result                                                                                         |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| Block calls              | Keep checking the remote catalog, but prevent new MCP calls                                    |
| Disable the Connection   | Stop catalog checks and new MCP calls while preserving the saved configuration and assignments |
| Remove an Agent Identity | Prevent new calls for that identity after the changed assignment is applied                    |
| Delete the Connection    | Remove its configuration and stop checks and new calls                                         |

Changes apply shortly after you save, not instantly. They do not cancel a remote call that already started.

To remove one Agent Identity, open the Connection detail page and find it in **Agent Identity assignments**. Each
assigned identity has a remove control, and Duale AI asks you to confirm before it saves the change. The section then
lists the remaining identities. You can remove the same assignment from the Agent Identity side: open the identity in
**Agent settings**, select **Tools**, and choose **Remove** on the Connection's row.

The organization catalog can retain expired Tool definitions, but it does not offer or call them. Before a new call,
Duale AI checks the current Connection, call policy, and assignment. [Operate
Tools](https://dev.duale.ai/en/docs/tools/operations.md) explains retained definitions and catalog freshness.

## Related content

- [Tool limits: Source, MCP, and Agent Identity boundaries](https://dev.duale.ai/en/docs/tools/limits.md)
- [MCP server compatibility and call contract](https://dev.duale.ai/en/docs/tools/reference.md)
- [Agent Tools: MCP servers, custom code, web research](https://dev.duale.ai/en/product/tools.md)
- [Tools: sources, Built-in Tools, and source selection](https://dev.duale.ai/en/docs/tools.md)
- [Operate Tools: catalog states and call outcomes](https://dev.duale.ai/en/docs/tools/operations.md)
- [Documentation: SDK, capabilities, and production boundary](https://dev.duale.ai/en/docs.md)

---

## Sitemap

See the full [Markdown sitemap](https://dev.duale.ai/sitemap.md) for all pages.