How to fix MCP server timeout errors

1# Error messages you might see:
2
3# In MCP host logs:
4# "Request timeout (-32001)"
5# "Tool execution timed out after 60000ms"
6# "MCP server request timed out"
7
8# In JSON-RPC format:
9# {
10#   "jsonrpc": "2.0",
11#   "error": {
12#     "code": -32001,
13#     "message": "Request timed out"
14#   },
15#   "id": 1
16# }
17
18# Check logs:
19tail -n 50 ~/Library/Logs/Claude/mcp*.log | grep -i timeout

1// claude_desktop_config.json — increase timeout to 2 minutes
2{
3  "mcpServers": {
4    "slow-api-server": {
5      "command": "node",
6      "args": ["./dist/index.js"],
7      "env": {
8        "MCP_SERVER_REQUEST_TIMEOUT": "120000",
9        "API_KEY": "your-key"
10      }
11    }
12  }
13}

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2import { z } from "zod";
3
4const server = new McpServer({
5  name: "progress-demo",
6  version: "1.0.0",
7});
8
9server.tool(
10  "process-large-dataset",
11  "Process a large dataset with progress updates",
12  { datasetId: z.string() },
13  async ({ datasetId }, { sendNotification }) => {
14    const totalItems = 1000;
15
16    for (let i = 0; i < totalItems; i += 100) {
17      // Process batch...
18      await processBatch(datasetId, i, i + 100);
19
20      // Send progress notification
21      await sendNotification({
22        method: "notifications/progress",
23        params: {
24          progressToken: datasetId,
25          progress: i + 100,
26          total: totalItems,
27        },
28      });
29    }
30
31    return {
32      content: [{ type: "text", text: `Processed ${totalItems} items` }],
33    };
34  }
35);

1server.tool(
2  "search-records",
3  "Search records with pagination",
4  {
5    query: z.string(),
6    cursor: z.string().optional(),
7    pageSize: z.number().optional().default(50),
8  },
9  async ({ query, cursor, pageSize }) => {
10    const offset = cursor ? parseInt(cursor, 10) : 0;
11    const results = await searchDatabase(query, offset, pageSize);
12    const hasMore = results.length === pageSize;
13    const nextCursor = hasMore ? String(offset + pageSize) : null;
14
15    return {
16      content: [
17        {
18          type: "text",
19          text: JSON.stringify({
20            results,
21            nextCursor,
22            hasMore,
23          }, null, 2),
24        },
25      ],
26    };
27  }
28);

1// Add timeout to fetch calls within tools
2async function fetchWithTimeout(
3  url: string,
4  timeoutMs: number = 30000
5): Promise<Response> {
6  const controller = new AbortController();
7  const timeout = setTimeout(() => controller.abort(), timeoutMs);
8
9  try {
10    const response = await fetch(url, { signal: controller.signal });
11    return response;
12  } finally {
13    clearTimeout(timeout);
14  }
15}
16
17// Use in your tool handler
18server.tool("api-call", "Call external API", { id: z.string() },
19  async ({ id }) => {
20    try {
21      const response = await fetchWithTimeout(
22        `https://api.example.com/items/${id}`,
23        30000 // 30 second timeout for API call
24      );
25      const data = await response.json();
26      return { content: [{ type: "text", text: JSON.stringify(data) }] };
27    } catch (error) {
28      if (error.name === "AbortError") {
29        return {
30          content: [{ type: "text", text: "API call timed out after 30s" }],
31          isError: true,
32        };
33      }
34      throw error;
35    }
36  }
37);