---
title: "Create and manage MCP Connections"
description: "A named MCP Connection makes a remote server's compatible Tools eligible for selected Agent Identities across your organization."
lang: en
status: public-preview
lastUpdated: 2026-09-26
url: https://duale.ai/en/docs/tools/mcp-connections
---

## AI-generated summary

Create and manage named MCP Connections that make remote server Tools eligible for selected Agent Identities, covering prerequisites, creation, assignment, and access controls.

- Requires config:read_config, tools:read_catalog, and agent:manage_tools permissions plus an AAL2 sign-in.
- All assigned Agent Identities share one remote account; no per-identity data reaches the server.
- No per-Tool selection or approval prompt exists; review the full remote catalog before allowing calls.
- Access controls include Block calls, Disable, Remove an Agent Identity, and Delete the Connection.
- Up to 1,000 Agent Identities can be assigned to a single 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
> does not provide per-Tool selection or an approval prompt for MCP calls. Review the remote account's permissions and
> the complete catalog before you allow calls.

## 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. Profile checks each permission for the resolved person, action, resource, and Tenant;
  [Identity](https://duale.ai/en/docs/identity.md) owns that model.
- A sign-in at the Platform's AAL2 assurance level for creation, catalog inspection, and assignment.
- 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://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://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://duale.ai/en/docs/tools/operations.md) explains catalog states, names, outcomes, and reliability.

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

These controls take effect after the Platform applies the changed configuration. 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://duale.ai/en/docs/tools/operations.md) explains retained definitions and catalog freshness.

There is no **Ask** policy, approval queue, or wait list for MCP Tools. If a person must approve an action, use the
two-step proposal pattern in [Secure integration](https://duale.ai/en/docs/security/secure-integration.md).

## Related content

- [Tools: named capabilities supplied by SDK and MCP sources](https://duale.ai/en/docs/tools.md)
- [Operate and troubleshoot MCP Connections](https://duale.ai/en/docs/tools/operations.md)
- [MCP compatibility, call contract, and Tool catalog API](https://duale.ai/en/docs/tools/reference.md)
- [Connect an MCP client to search documentation](https://duale.ai/en/docs/mcp.md)
- [Tool publication and presentation limits](https://duale.ai/en/docs/tools/limits.md)
- [Secure integrations against redelivery and uncertainty](https://duale.ai/en/docs/security/secure-integration.md)

---

## Sitemap

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