Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions docs/design/mcp-safe-replay.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Safe replay after MCP connection loss

## Problem

An MCP tool can complete a side effect before its response connection fails. Reconnecting and sending the same `tools/call` again can therefore repeat a write while the user sees only the second result. MCP tool annotations are optional and default to non-idempotent behavior, so missing annotations cannot justify automatic replay.

## Replay policy

Qwen Code automatically replays a failed invocation only when all of the following are true:

- The failure is classified as a connection loss by the existing MCP connection checks.
- The MCP server has `trust: true`.
- The current workspace passes the workspace trust gate.
- The tool declares `idempotentHint: true`, or declares `readOnlyHint: true` without `destructiveHint: true` or `idempotentHint: false`.

Conflicting annotations are not treated as safe. In particular, a tool that declares itself read-only while also declaring destructive or non-idempotent behavior is not replayed. An explicit idempotency declaration can cover a mutating operation, but it does not override contradictory read-only annotations.

The same decision is applied to both execution paths: the direct MCP client used for progress-aware calls and the callable fallback. Abort errors, non-connection errors, and MCP `isError: true` protocol results retain their existing behavior.

After reconnecting, Qwen Code applies the same trust and annotation checks to the newly discovered tool before sending the replay. It does not carry a previous server process's trust or annotations into the new invocation.

## Failure behavior

When a connection failure is not safe to replay, the current invocation does not reconnect or construct a second invocation. It returns a stable error explaining that the operation may have completed and must not be retried automatically. The error does not include tool arguments or the upstream transport error.

Connection recovery for later, independent calls remains the responsibility of the existing health monitor, an explicit reconnect, or the normal discovery lifecycle. Safe calls retain the existing bounded reconnect behavior.

## Compatibility

This is an intentional conservative change. Tools without annotations no longer receive transparent connection-loss replay, even when an older Qwen Code release retried them. Servers that want replay must provide accurate annotations, and administrators must opt into server trust in a trusted workspace.

MCP annotations are behavior hints supplied by the server, not an authorization boundary. Qwen Code uses them for replay only after both server and workspace trust gates pass.

## Verification

Tests cover the direct client and callable fallback, safe idempotent and read-only declarations, missing and contradictory annotations, both trust gates, re-discovered tools that lose trust or annotations, connection error classification, aborts, protocol errors, reconnect failure, and the retry limit. A separate local E2E record exercises a server that commits a side effect before dropping the response connection and verifies that an unsafe call reaches the server only once.
13 changes: 8 additions & 5 deletions docs/developers/tools/mcp-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,8 @@ Each discovered MCP tool is wrapped in a `DiscoveredMCPTool` instance that:
- **Processes responses** for both the LLM context and user display
- **Maintains connection state** and handles timeouts

After a connection loss, the current invocation is replayed only for a trusted server in a trusted workspace when the tool explicitly declares `idempotentHint: true`, or declares `readOnlyHint: true` without a conflicting `destructiveHint: true` or `idempotentHint: false`. Missing or conflicting annotations, and annotations from an untrusted server or workspace, are treated as unsafe because the server may have completed a side effect before the response was lost. Tool authors should publish accurate MCP annotations; administrators should still verify them before enabling server trust.

### Transport Mechanisms

The CLI supports three MCP transport types:
Expand Down Expand Up @@ -114,7 +116,7 @@ Each server configuration supports the following properties:
- **`env`** (object): Environment variables for the server process. Values can reference environment variables using `$VAR_NAME` or `${VAR_NAME}` syntax
- **`cwd`** (string): Working directory for Stdio transport
- **`timeout`** (number): Request timeout in milliseconds (default: 600,000ms = 10 minutes)
- **`trust`** (boolean): When `true`, bypasses all tool call confirmations for this server (default: `false`)
- **`trust`** (boolean): When `true`, bypasses tool call confirmations for this server in a trusted workspace (default: `false`)
- **`includeTools`** (string[]): List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default.
- **`excludeTools`** (string[]): List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server. **Note:** `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded.
- **`targetAudience`** (string): The OAuth Client ID allowlisted on the IAP-protected application you are trying to access. Used with `authProviderType: 'service_account_impersonation'`.
Expand Down Expand Up @@ -446,9 +448,10 @@ Each `DiscoveredMCPTool` implements sophisticated confirmation logic:
#### Trust-based Bypass

```typescript
if (this.trust) {
return false; // No confirmation needed
if (this.trust === true && this.cliConfig?.isTrustedFolder()) {
return 'allow';
}
return 'ask';
```

#### Dynamic Allow-listing
Expand Down Expand Up @@ -618,7 +621,7 @@ The MCP integration tracks several states:

### Security Considerations

- **Trust settings:** The `trust` option bypasses all confirmation dialogs. Use cautiously and only for servers you completely control
- **Trust settings:** The `trust` option bypasses tool confirmation dialogs only in a trusted workspace. Use cautiously and only for servers you completely control
- **Access tokens:** Be security-aware when configuring environment variables containing API keys or tokens
- **Sandbox compatibility:** When using sandboxing, ensure MCP servers are available within the sandbox environment
- **Private data:** Using broadly scoped personal access tokens can lead to information leakage between repositories
Expand Down Expand Up @@ -789,7 +792,7 @@ qwen mcp add [options] <name> <commandOrUrl> [args...]
- `-e, --env`: Set environment variables (e.g. -e KEY=value).
- `-H, --header`: Set HTTP headers for SSE and HTTP transports (e.g. -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123").
- `--timeout`: Set connection timeout in milliseconds.
- `--trust`: Trust the server (bypass all tool call confirmation prompts).
- `--trust`: Trust the server (bypass its tool call confirmations in a trusted workspace).
- `--description`: Set the description for the server.
- `--include-tools`: A comma-separated list of tools to include.
- `--exclude-tools`: A comma-separated list of tools to exclude.
Expand Down
2 changes: 1 addition & 1 deletion docs/users/configuration/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -593,7 +593,7 @@ Configures connections to one or more Model-Context Protocol (MCP) servers for d
| `mcpServers.<SERVER_NAME>.httpUrl` | string | The URL of an MCP server that uses streamable HTTP for communication. | Yes |
| `mcpServers.<SERVER_NAME>.headers` | object | A map of HTTP headers to send with requests to `url` or `httpUrl`. | Yes |
| `mcpServers.<SERVER_NAME>.timeout` | number | Timeout in milliseconds for requests to this MCP server. | Yes |
| `mcpServers.<SERVER_NAME>.trust` | boolean | Trust this server and bypass all tool call confirmations. | Yes |
| `mcpServers.<SERVER_NAME>.trust` | boolean | Trust this server and bypass its tool call confirmations in a trusted workspace. | Yes |
| `mcpServers.<SERVER_NAME>.description` | string | A brief description of the server, which may be used for display purposes. | Yes |
| `mcpServers.<SERVER_NAME>.includeTools` | array of strings | List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default. | Yes |
| `mcpServers.<SERVER_NAME>.excludeTools` | array of strings | List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server. **Note:** `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. | Yes |
Expand Down
14 changes: 11 additions & 3 deletions docs/users/features/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -271,7 +271,15 @@ environment. This is kept as an escape hatch for at least one release.

### Trust (skip confirmations)

- **Server trust** (`trust: true`): bypasses confirmation prompts for that server (use sparingly).
- **Server trust** (`trust: true`): bypasses confirmation prompts for that server only in a trusted workspace (use sparingly).

### Connection-loss replay

Qwen Code only reconnects and replays the current MCP tool call when the server has `trust: true`, the workspace is trusted, and the tool explicitly declares either `idempotentHint: true` or a consistent read-only annotation. Read-only annotations conflict with `destructiveHint: true` or `idempotentHint: false` and are not replayed.

Calls with missing annotations, conflicting annotations, an untrusted server, or an untrusted workspace are not replayed after a connection failure. Qwen Code reports that the result may be unknown because the server could have completed the operation before the response was lost. Verify the outcome before trying again. This conservative behavior can differ from earlier releases that transparently retried unannotated tools.

Annotations are server-provided behavior hints, not permissions or an authorization boundary. Only configure `trust: true` for servers you control and whose annotations you have verified.

### OAuth authentication

Expand Down Expand Up @@ -453,7 +461,7 @@ Optional:
| `env` | object | Environment variables for the server process. Values can reference environment variables using `$VAR_NAME` or `${VAR_NAME}` syntax |
| `cwd` | string | Working directory for Stdio transport |
| `timeout` | number<br>(default: 600,000) | Request timeout in milliseconds (default: 600,000ms = 10 minutes) |
| `trust` | boolean<br>(default: false) | When `true`, bypasses all tool call confirmations for this server (default: `false`) |
| `trust` | boolean<br>(default: false) | When `true`, bypasses tool call confirmations for this server in a trusted workspace (default: `false`) |
| `includeTools` | array | List of tool names to include from this MCP server. When specified, only the tools listed here will be available from this server (allowlist behavior). If not specified, all tools from the server are enabled by default. |
| `excludeTools` | array | List of tool names to exclude from this MCP server. Tools listed here will not be available to the model, even if they are exposed by the server.<br>Note: `excludeTools` takes precedence over `includeTools` - if a tool is in both lists, it will be excluded. |
| `targetAudience` | string | The OAuth Client ID allowlisted on the IAP-protected application you are trying to access. Used with `authProviderType: 'service_account_impersonation'`. |
Expand Down Expand Up @@ -481,7 +489,7 @@ qwen mcp add [options] <name> <commandOrUrl> [args...]
| `-e`, `--env` | Set environment variables. | — | `-e KEY=value` |
| `-H`, `--header` | Set HTTP headers for SSE and HTTP transports. | — | `-H "X-Api-Key: abc123"` |
| `--timeout` | Set connection timeout in milliseconds. | — | `--timeout 30000` |
| `--trust` | Trust the server (bypass all tool call confirmation prompts). | — (`false`) | `--trust` |
| `--trust` | Trust the server; skip confirmations in trusted workspaces. | — (`false`) | `--trust` |
| `--description` | Set the description for the server. | — | `--description "Local tools"` |
| `--include-tools` | A comma-separated list of tools to include. | all tools included | `--include-tools mytool,othertool` |
| `--exclude-tools` | A comma-separated list of tools to exclude. | none | `--exclude-tools mytool` |
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/commands/mcp/add.ts
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,7 @@ export const addCommand: CommandModule = {
})
.option('trust', {
describe:
'Trust the server (bypass all tool call confirmation prompts)',
'Trust the server (bypass its tool call confirmations in a trusted workspace)',
type: 'boolean',
})
.option('description', {
Expand Down
Loading
Loading