Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When registering an HTTP MCP server via `claude mcp add --transport http`, there is no way to configure a per-server tool call timeout. The current hard limit appears to be ~60 seconds, which makes it impossible to use MCP tools that perform legitimately long operations — heavy data queries, AI agent workflows, batch processing, large report generation, etc.

Concrete example: A Snowflake-hosted Cortex AI agent (Nessie) exposed as an HTTP MCP server times out consistently when asked to search call transcripts or run analytical queries that take 60–180 seconds on the server side. The tool returns `"The operation timed out"` with no partial result and no way to recover other than retrying with a simpler query.

This is not a server performance problem. The Snowflake backend completes the work — the client-side ceiling prevents the result from arriving.

Related Issues

• #50289 — `.mcp.json` per-server `timeout` field was honored before v2.1.113 but is now silently ignored for HTTP transport (regression). This confirms the mechanism existed and worked; it just needs to be exposed via the CLI and fixed.
• #52137 — Proposes SEP-1686 (Tasks) as the structural fix for async long-running calls. That's the right long-term solution; the feature requested here is the short-term pragmatic fix.
• #43342 / #44006 — Reports of MCP tools hanging indefinitely with no timeout or cancellation path.

Proposed Solution

Add a `--timeout` flag to `claude mcp add` (and the equivalent `mcpServers` JSON field in `.mcp.json`) that sets the per-server tool call timeout in milliseconds:

```bash

Register an HTTP MCP server with a 5-minute timeout

claude mcp add
--transport http
--timeout 300000
-s user
snowflake
https://my-instance.snowflakecomputing.com/api/v2/.../mcp-servers/MY_SERVER
--header "Authorization: Bearer $PAT" ```

Equivalent `.mcp.json` form (already partially specced, broken since #50289): ```json { "mcpServers": { "snowflake": { "type": "http", "url": "https://...", "headers": { "Authorization": "Bearer ..." }, "timeout": 300000 } } } ```

Why This Matters Beyond My Use Case

The class of operations that legitimately exceeds 60s is broad and growing:

• AI agent backends — Cortex AI (Snowflake), OpenAI Assistants, LangGraph — all run multi-step reasoning that can take 1–5 minutes
• Bulk data queries — analytics warehouses (Snowflake, BigQuery, Redshift) on large datasets
• PDF / document processing — download + parse + extract pipelines
• Publisher API fetches — rate-limited upstream APIs with variable latency
• Batch operations — anything that processes N items before returning

A configurable timeout is the pragmatic fix that unblocks these today, independent of whether SEP-1686 (Tasks) is eventually implemented. Both can coexist: the timeout protects against truly hung calls while Tasks enables structured async patterns.

Priority

High — blocks real enterprise use cases where Claude Code is the interface to heavy backend systems (data warehouses, AI agents, document pipelines).

Feature Category

MCP server integration

Additional Context

• Claude Code version where this was tested: 2.1.114+ (macOS arm64)
• MCP server transport: HTTP (`--transport http`)
• Timeout behavior: hard ~60s ceiling regardless of server configuration
• The `.mcp.json` `timeout` field was honored in ≤2.1.107 per #50289, so the implementation precedent exists