Skip to content

request-timeouts.md

Latest commit

 

History

History
151 lines (108 loc) · 3.63 KB

request-timeouts.md

File metadata and controls

151 lines (108 loc) · 3.63 KB
Raw

Request Timeouts

Control how long mcp2cli waits for MCP server responses — globally via config, or per-command via the --timeout flag.

Default Behavior

Every MCP operation has a 120-second timeout by default. If the server doesn't respond within this window, the command fails with a timeout error rather than hanging indefinitely.

Configuration

In Config YAML

Set the default timeout for all operations on a server:

defaults:
  timeout_seconds: 60    # 60 seconds for all operations

Per-Command Override

Override the config default for a single invocation:

# Quick draft list — 5 second timeout
email --timeout 5 draft list

# Long-running operation — 10 minute timeout
email --timeout 600 search --query "from:boss"

# Disable timeout entirely
email --timeout 0 search --query "has:attachment" --all

Timeout Values

Value Behavior
120 (default) 2-minute timeout on all operations
1–N Custom timeout in seconds
0 No timeout — wait indefinitely

How It Works

sequenceDiagram
    participant User
    participant CLI as CLI Parser
    participant Context as AppContext
    participant Client as MCP Client
    participant Server as MCP Server

    User->>CLI: email --timeout 30 search --query hi
    CLI->>Context: timeout_override = Some(30)
    Context->>Context: resolve_timeout() → 30s
    Context->>Client: tokio::time::timeout(30s, perform(...))
    
    alt Response within 30s
        Client->>Server: tools/call
        Server-->>Client: Result
        Client-->>Context: Ok(result)
        Context-->>User: Output
    else Timeout exceeded
        Client--xContext: Elapsed
        Context-->>User: Error: operation timed out after 30s
    end
Loading

The timeout wraps the entire perform() call, which includes:

  • Transport-level connection setup
  • JSON-RPC request/response roundtrip
  • Notification handling during the operation
  • SSE stream reading (for HTTP transport)

Precedence Rules

Timeout is resolved in this order (first match wins):

  1. --timeout CLI flag — per-command override
  2. defaults.timeout_seconds in config YAML — per-server default
  3. Built-in default — 120 seconds
# Config says 60s, but this command uses 10s:
email --timeout 10 draft list

# Config says 60s, no flag → 60s:
email search --query "from:boss"

# No config override, no flag → 120s (built-in default):
mcp2cli --url https://mcp.example.com/email search --query "from:boss"

Practical Examples

Fast-fail health checks

# CI health check — fail fast if server is down
email --timeout 5 labels list || echo "Server unreachable"

Long-running data operations

# Mailbox-wide search that might take minutes
email --timeout 0 search --query "has:attachment" --all

Scripted retries with timeout

for i in 1 2 3; do
  if email --timeout 10 --json send --to "$RECIPIENT" --subject "Report" --body "..." 2>/dev/null; then
    echo "Send succeeded"
    break
  fi
  echo "Attempt $i timed out, retrying..."
  sleep 5
done

Different environments, different timeouts

# configs/dev.yaml
defaults:
  timeout_seconds: 30       # Fast iteration

# configs/prod.yaml
defaults:
  timeout_seconds: 300      # Production needs more time

See Also