--- title: "Operate and troubleshoot MCP Connections" description: "MCP Connection operations cover monitoring connection state, catalog freshness, tool compatibility, and call outcomes to verify availability and troubleshoot failures." lang: en status: public-preview lastUpdated: 2026-09-26 url: https://duale.ai/en/docs/tools/operations --- ## AI-generated summary Operate MCP Connection state, catalog freshness, model-facing Tool names, call outcomes, and troubleshooting for Duale AI Tools. - Connection policy determines whether catalog checks run and whether new MCP calls are permitted. - Catalog freshness tracks states from Not observed through Active, Expired, and No Tools reported. - Model-facing Tool names use mcp_ or sdk_ prefixes with collision qualification by Source context. - Analytics records one final outcome per Tool Call, excluding catalog checks, with named outcome categories. - A troubleshooting table maps symptoms like Expired to first checks and safe next actions. Summaries were generated by AI. --- Under **Tools**, use **Status** and **Catalog** to see whether an MCP Connection is enabled, whether its Source is current, and which Tools Duale AI can offer. Use **Analytics** to inspect recorded final outcomes for MCP and SDK Tool Calls. Catalog state describes current availability; historical reliability does not prove that a server is reachable now or that the next call will succeed. [Tools reference](https://duale.ai/en/docs/tools/reference.md) owns MCP server compatibility, the synchronous MCP call contract, static MCP limits, and the organization Tool catalog API. ## Operate MCP Connection state ### Connection policy | State | What it means | What to do next | | -------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------- | | Enabled, allow calls | Catalog checks run and compatible Tools can be offered after a successful check | Inspect catalog freshness and test a low-risk call | | Enabled, block calls | Catalog checks continue, but new MCP calls are blocked | Review the catalog or allow calls when ready | | Disabled | Catalog checks and new MCP calls stop; configuration and assignments remain saved | Enable the Connection when you want checks to resume | While the Dashboard fetches catalog status, it shows **Loading**. If that read fails, it shows **Unavailable**. Retry the read; this state does not prove that the remote MCP server is unavailable. ### Catalog freshness | State | What it means | What to do next | | ----------------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | Not observed | No successful complete catalog check exists yet | Check the endpoint and remote credential; Duale AI keeps trying while enabled | | Active | The latest successful complete catalog check is still fresh | Inspect Tool compatibility; this state does not run or verify a Tool | | Expired | No successful catalog check refreshed the Source within seven minutes | Check remote availability and access; expired Tools are not offered for new model turns | | No Tools reported | A successful complete check returned an empty catalog | Confirm that the remote account is permitted to list Tools | After a successful check, Duale AI normally checks again after five minutes plus up to 10% positive jitter. After failed checks, it retries after 5, 10, and then 15 minutes; the 15-minute interval repeats while the Connection remains enabled. A failed check does not refresh the active window. These states show whether Duale AI has a recent successful catalog, not why a check failed. **Not observed** and **Expired** do not distinguish DNS, TLS, authentication, protocol, pagination, or limit failures. ## Review a changing MCP catalog An MCP server owns its catalog and can change it without a Duale AI release. After a successful complete check, the latest definitions replace or refresh the previous catalog. Every compatible Tool added later becomes eligible for every assigned Agent Identity when calls are allowed. There is no per-Tool allowlist, exclusion, or catalog-version approval in this release. If you need a controlled Tool lifecycle, publish the approved functions through an [SDK Tool Host](https://duale.ai/en/docs/sdk/tools.md). [Tool limits](https://duale.ai/en/docs/tools/limits.md) states how far a catalog can grow before a check or an Agent Identity reaches a ceiling. The Catalog view keeps incompatible Tools visible with a reason, but does not expose them to a model. A Tool is incompatible when the model path cannot represent its input schema, when it declares a dynamic transport header the protocol does not accept, or when it needs one and the server negotiated a protocol revision that cannot carry it. Dynamic transport headers are supported on the `2026-07-28` revision. On an earlier revision the header cannot be sent at all, so the Tool stays incompatible until the server offers that revision. Tool names, titles, descriptions, input-schema text, and server annotations are content you do not control. They can influence model Tool selection and proposed arguments. Annotations such as read-only, destructive, idempotent, or open-world are hints only. Duale AI does not automatically classify a Tool from its schema or annotations, grant access, or change call policy. Expired Tools remain visible with their last successful definitions and assignments, but they cannot be offered or called. They can remain visible after checks stop because the Connection was disabled or deleted. This release has no Connection control that permanently deletes these historical entries. ## Understand model-facing Tool names The Catalog view shows both the native Tool name reported by the server and the short model-facing name used during execution. A unique Tool normally starts with `mcp_` followed by a readable form of its native name. SDK Tools start with `sdk_`. If two Tools would receive the same model-facing name, Duale AI qualifies every member of the collision with readable Source context. If that still collides, it adds a short stable suffix. It never merges Tools from different Sources, even when their schemas match, because those Sources can use different credentials and data. For example, if **CRM Production** and **CRM Sandbox** both expose `search_contacts`, Duale AI qualifies both names, such as `mcp_crm_production_search_contacts` and `mcp_crm_sandbox_search_contacts`. It does not leave one Tool as `mcp_search_contacts` while renaming only the other, and it does not expose a Connection UUID to the model. Duale AI computes names from the current catalog and does not reserve them permanently. A catalog change can therefore change a model-facing name. Duale AI reads the current active Tool set before each model turn. Once it accepts a Tool Call, it keeps that call bound to the selected Connection and native Tool instead of following a later alias change. Duale AI still considers the names of expired Tools when it keeps model-facing names unique. Expiring or deleting a Connection therefore does not by itself shorten another Tool's qualified name. ## Read call outcomes and reliability Analytics counts one final outcome for each requested Tool Call, not each internal attempt. It excludes catalog checks. The organization view provides an aggregate and breakdowns by Tool Source, model-facing Tool name, and Agent Identity. | Outcome | Meaning | | --------------------- | ------------------------------------------------------------------------ | | Succeeded | Duale AI received and accepted a supported result for the call | | Failed | The call ended with a confirmed failure | | Outcome unknown | Duale AI cannot rule out remote execution, but cannot prove its result | | Blocked | Connection policy prevented the call | | Denied | Current assignment or authorization prevented the call | | Unsupported | The Tool or returned result is outside this release's supported contract | | Cancelled before send | The call ended before remote execution started | | Other | The recorded outcome is not one of the current named categories | **Confirmed success rate** is `succeeded / (succeeded + failed)`, shown as a percentage rounded to two decimal places. An unknown, blocked, denied, unsupported, cancelled, or other outcome is outside that denominator. When there are no confirmed outcomes, the Dashboard shows no confirmed rate. Analytics are aggregate operational evidence. They do not show Tool arguments or results, prove the state of an external system, or replace a per-call business or audit record. [Evidence and audit](https://duale.ai/en/docs/security/evidence-and-audit.md) explains which Platform records are available and what they cannot prove. ## Respond to a temporary MCP Tool pause A Tool Call can appear as **temporarily unavailable** while Duale AI pauses that Connection-and-Tool pair after recent technical failures. Catalog checks and other Tools on the Connection continue. Retry after the reported time. The [Tools reference](https://duale.ai/en/docs/tools/reference.md#understand-the-mcp-call-contract) defines the pause rule. ## Troubleshoot an MCP Connection from the visible symptom | Symptom | First check | Safe next action | | ------------------------------------ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | Catalog status unavailable | Whether the Dashboard catalog-status read failed | Retry the read; do not infer remote-server health from this state | | Not observed | Endpoint format, remote availability, and credential | Correct the Connection and wait for the next check | | Expired | Last successful check and remote access | Restore the server or credential; checks continue while enabled | | No Tools reported | Remote account's `tools/list` result | Grant only the list access needed, then wait for a successful check | | Tool is incompatible | Reason shown in Catalog | Read the reason: a schema the model path cannot carry needs a remote change, a protocol revision needs a server upgrade | | Calls are blocked or denied | Connection call policy and Agent Identity assignment | Change only the policy or assignment that must admit the call | | Tool Call is temporarily unavailable | Recent technical failures for that exact Tool | Wait until the reported retry time, then test once | | Outcome unknown | Destination system's own record | Reconcile the external state before retrying or compensating | When a server is down, Duale AI keeps checking until you disable or delete the Connection. Do not repeatedly delete and recreate a Connection to force recovery; correct the endpoint or remote access and let the next successful check refresh the catalog. The Dashboard does not expose the exact reason for a failed catalog check. If the endpoint and credential appear correct and the state does not recover, email [technical support](mailto:contact+support@mail.duale.ai). Include the Connection ID, Connection name, current status, approximate time of the problem, and the displayed last successful check time if present. Never send the bearer token, API key, or unrestricted logs by email. ## Related content - [MCP compatibility, call contract, and Tool catalog API](https://duale.ai/en/docs/tools/reference.md) - [Create and manage MCP Connections](https://duale.ai/en/docs/tools/mcp-connections.md) - [Tools: named capabilities supplied by SDK and MCP sources](https://duale.ai/en/docs/tools.md) - [Connect an MCP client to search documentation](https://duale.ai/en/docs/mcp.md) - [Secure integrations against redelivery and uncertainty](https://duale.ai/en/docs/security/secure-integration.md) - [Security decision points for Task execution](https://duale.ai/en/docs/security.md) --- ## Sitemap See the full [Markdown sitemap](https://duale.ai/sitemap.md) for all pages.