Mcp Timeouts Config

Configure timeout thresholds for MCP server startup and tool execution to prevent hangs.

When to Use This Setting

Apply this setting when you need to:

• Accommodate MCP servers that require longer startup times due to heavy initialization or remote connections
• Prevent tool execution hangs by setting explicit timeout boundaries for long-running operations
• Control the maximum output size from MCP tools to prevent context window overflow Consider alternatives when:
• Your MCP servers start quickly and tools execute within the default timeout windows
• You want to set timeouts at the individual server level rather than globally for all MCP operations

Quick Start

Configuration

Copy
name: mcp-timeouts-config
type: setting
category: mcp

Example Application

Copy
claude setting:apply mcp-timeouts-config

Example Output

Setting applied. Changes:
- MCP_TIMEOUT: 30000 (server startup, 30 seconds)
- MCP_TOOL_TIMEOUT: 60000 (tool execution, 60 seconds)
- MAX_MCP_OUTPUT_TOKENS: 50000 (output token limit)

Core Concepts

Timeout Configuration Overview

Aspect	Details
MCP_TIMEOUT	Maximum milliseconds allowed for an MCP server to complete its startup sequence
MCP_TOOL_TIMEOUT	Maximum milliseconds allowed for a single tool invocation to return results
MAX_MCP_OUTPUT_TOKENS	Maximum token count for output from any single MCP tool response
Failure Behavior	Operations exceeding timeouts are terminated and return an error to Claude Code

Timeout Flow Architecture

+---------------------------+
|  MCP Server Startup       |
|  Timeout: 30,000ms        |
+---------------------------+
         |
    success / timeout
         |
         v
+---------------------------+
|  Tool Invocation          |
|  Timeout: 60,000ms        |
+---------------------------+
         |
    success / timeout
         |
         v
+---------------------------+
|  Output Processing        |
|  Max Tokens: 50,000       |
+---------------------------+
         |
    within limit / truncated
         |
         v
+---------------------------+
|  Result to Claude Code    |
+---------------------------+

Configuration

Parameter	Type	Default	Description
MCP_TIMEOUT	string	"30000"	Server startup timeout in milliseconds, increase for slow-starting servers
MCP_TOOL_TIMEOUT	string	"60000"	Tool execution timeout in milliseconds, increase for long-running operations
MAX_MCP_OUTPUT_TOKENS	string	"50000"	Maximum tokens allowed in MCP tool output before truncation
description	string	N/A	Explanation of the timeout configuration rationale
env	object	N/A	Container for environment variable key-value pairs

Best Practices

1. Set startup timeout based on your slowest server - Measure the actual startup time of each MCP server and set MCP_TIMEOUT to at least 150% of the slowest one. This provides headroom for system load variations.
2. Use tool timeout to match operation complexity - Database queries, API calls, and file system scans have different execution profiles. Set MCP_TOOL_TIMEOUT to accommodate your most complex typical operation.
3. Limit output tokens to protect context budget - Large MCP tool outputs can consume a significant portion of the context window. Set MAX_MCP_OUTPUT_TOKENS to no more than 25% of your total context budget.
4. Monitor timeout occurrences - If you see frequent timeout errors, investigate whether the MCP server or tool is actually hanging or simply needs more time. Persistent timeouts may indicate a server bug.
5. Create per-project timeout profiles - Projects with local MCP servers need shorter timeouts than projects with remote servers. Maintain separate timeout configurations for local and remote development scenarios.

Common Issues

1. Server fails to start within timeout - Increase MCP_TIMEOUT incrementally. Common causes include slow Docker container startup, remote server handshakes, or heavy initialization logic.
2. Tool execution times out on large datasets - If a tool processes large amounts of data, increase MCP_TOOL_TIMEOUT. Consider whether the tool can be optimized to process data in smaller chunks.
3. Output truncated unexpectedly - When MAX_MCP_OUTPUT_TOKENS is too low, tool responses are cut off mid-content. Increase the limit if you need complete output, but monitor context window usage.