--- title: "MCP server compatibility and call contract" description: "MCP server compatibility requirements and call contract rules, including supported protocol versions, authentication modes, and failure handling." lang: en status: public-preview lastUpdated: 2026-10-26 url: https://dev.duale.ai/en/docs/tools/reference --- ## AI-generated summary This reference covers MCP server compatibility, authentication modes, and the MCP call contract for Duale AI connections. - MCP server compatibility and protocol version requirements. - Authentication mode selection for a named Connection. - Reserved argument names and Tool incompatibility. - Synchronous call results, retry limits, and failure pause. Summaries were generated by AI. --- To set up a server, [connect an MCP server](https://dev.duale.ai/en/docs/tools/mcp-connections.md). To read its states, [operate Tools](https://dev.duale.ai/en/docs/tools/operations.md). To recover from a failure, [troubleshoot Tools](https://dev.duale.ai/en/docs/tools/troubleshooting.md). [MCP catalog and call limits](https://dev.duale.ai/en/docs/tools/limits.md#mcp-catalog-and-call-limits) lists the size and count limits. ## Confirm MCP server compatibility An MCP Connection supports Streamable HTTP at one exact public HTTPS URL. The server must negotiate MCP `2025-06-18`, `2025-11-25`, or `2026-07-28` and answer catalog and Tool requests at that URL. Duale AI uses HTTP/1.1, does not follow redirects, does not retain server cookies, requests an uncompressed response, and rejects a compressed response. A server that negotiates an older MCP revision, or that depends on a redirect, cookie state, compression, or HTTP/2, is not compatible. A Tool that declares a dynamic transport header needs a server that negotiates `2026-07-28`. On an earlier revision, Duale AI cannot send that header, so the Tool stays incompatible until the server offers `2026-07-28`. ## Choose one authentication mode Choose no authentication, one bearer token, or one API key in an allowed custom header. The same credential applies to catalog checks and Tool Calls for that named Connection. ## Understand the MCP call contract ### Avoid reserved argument names Duale AI reserves every top-level argument name that starts with two underscores (`__`). A remote Tool whose input schema declares one, as a property or in `required`, stays visible in **Catalog** as incompatible and is never offered to a model. The rule does not affect the Connection's other Tools or nested fields. [Reserved argument names](https://dev.duale.ai/en/docs/tools/limits.md#reserved-argument-names) explains how to recognize and fix the Tool. ### Return one complete result Duale AI supports synchronous MCP calls that return a complete text or structured result. It does not continue interactive `input_required` responses, queued MCP Tasks, or a task handle returned for later retrieval. Image, audio, embedded resource, and resource-link result blocks are not supported. Duale AI cannot guarantee exactly-once execution for a remote MCP Tool. When Duale AI cannot rule out that the server received a request, it does not intentionally retry that call. If it also cannot prove the response, the call ends as **Outcome unknown**, as [Read a Tool Call outcome](https://dev.duale.ai/en/docs/agent-harness.md#read-a-tool-call-outcome) defines. Make state-changing remote operations idempotent where possible. Check the destination system before any manual retry or compensation. After three consecutive technical failures for one Tool, such as transport errors or invalid results, Duale AI pauses calls to that Tool on that Connection for 30 seconds. A call during the pause is not sent to the server; it reports that the Tool is temporarily paused, and Analytics counts it as **Failed**. Catalog checks and other Tools on the Connection continue. The next call after the pause can test the Tool again. ## Related content - [Operate Tools: catalog states and call outcomes](https://dev.duale.ai/en/docs/tools/operations.md) - [Create and manage MCP Connections](https://dev.duale.ai/en/docs/tools/mcp-connections.md) - [Connect an MCP client to the documentation server](https://dev.duale.ai/en/docs/mcp.md) - [Tool limits: Source, MCP, and Agent Identity boundaries](https://dev.duale.ai/en/docs/tools/limits.md) - [Agent Tools: MCP servers, custom code, web research](https://dev.duale.ai/en/product/tools.md) - [Legal: every point quoted, ready for decision](https://dev.duale.ai/en/use-cases/legal.md) --- ## Sitemap See the full [Markdown sitemap](https://dev.duale.ai/sitemap.md) for all pages.