[FEATURE] Add --timeout flag to `claude mcp add --transport http` for long-running MCP tool calls

[talhalegua]

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

• [BUG] .mcp.json per-server timeout field no longer honored for HTTP MCP tool calls since 2.1.113 (native binary transition) #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.
• [FEATURE] Implement SEP-1686 (Tasks) client support to unblock long-running MCP tool calls in Cowork / Desktop #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.
• Plugin MCP tools hang indefinitely with no timeout or error #43342 / [BUG] MCP tool calls hang indefinitely with no way to cancel byt itself #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 [BUG] .mcp.json per-server timeout field no longer honored for HTTP MCP tool calls since 2.1.113 (native binary transition) #50289, so the implementation precedent exists

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] .mcp.json per-server timeout field no longer honored for HTTP MCP tool calls since 2.1.113 (native binary transition) #50289
2. [FEATURE] Make MCP tool call timeout configurable (MCP_TOOL_TIMEOUT) #47076
3. [FEATURE] Make MCP Tool Execution Timeout Configurable in Claude Desktop #22542

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically closed as a duplicate of #50289.

If this is incorrect, please re-open this issue or create a new one.

🤖 Generated with Claude Code

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.