Request Timeouts · mcp2cli

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

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):

--timeout CLI flag — per-command override
defaults.timeout_seconds in config YAML — per-server default
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

defaults:
  timeout_seconds: 30       # Fast iteration

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