MCP Server stdio Connection Lockup After Cancelled Batch Operations

[IS-GYG]

GitHub Issue: MCP Server stdio Connection Lockup After Cancelled Batch Operations

Repository: microsoft/azure-devops-mcp
Type: Bug Report
Severity: High (Blocks all MCP operations until VS Code restart)

---

Issue Title

stdio connection lockup after cancelled/timeout batch operations prevents reconnection without VS Code restart

---

Description

When a batch operation (particularly wit_update_work_items_batch) is cancelled mid-execution or times out, the MCP server's stdio connection enters an unrecoverable state. VS Code caches the stdio pipe reference to the now-dead Node process, and even after killing the Node process, VS Code cannot establish a new connection without using the MCP Server Manager UI.

Environment

• MCP Server Version: 2.4.0 (via npx @azure-devops/mcp)
• VS Code Version: 1.96.x
• OS: Windows 11
• Connection Type: stdio (StdioServerTransport)
• Model: Claude Opus 4.5 / Claude Haiku 4.5 via GitHub Copilot Agent Mode

Steps to Reproduce

1. Configure MCP server in .vscode/mcp.json using stdio transport
2. Start a large batch operation (e.g., wit_update_work_items_batch with 32 items)
3. Cancel the operation mid-execution (user stops Copilot, network timeout, etc.)
4. All subsequent MCP tool calls return: "Tool <tool_name> is currently disabled by the user"
5. Killing the Node process (Get-Process node | Stop-Process) does NOT restore connectivity
6. Only recovery: VS Code MCP Server Manager (Ctrl+Shift+P → "MCP: List Servers" → Select → "Start Server")

Root Cause Analysis

The stdio Pipe Caching Problem

From src/index.ts#L111-L115:

const transport = new StdioServerTransport();
await server.connect(transport);

When VS Code connects to the MCP server via stdio:

1. VS Code creates a child process for the MCP server
2. A stdio pipe is established between VS Code and the child process
3. When the Node process dies unexpectedly (cancelled batch, crash):
   • The stdio pipe on the VS Code side becomes a "dead socket"
   • VS Code maintains a cached reference to this dead connection
   • New processes cannot use the same stdio pipe

Why Process Kill Alone Doesn't Work

# This finds and kills the MCP process
Get-Process -Name node | Where-Object { 
    (Get-WmiObject Win32_Process -Filter "ProcessId=$($_.Id)").CommandLine -like "*@azure-devops/mcp*" 
} | Stop-Process -Force

Even after killing the process:

• VS Code's MCP client still holds a reference to the dead pipe
• Starting a new Node process doesn't inherit the original stdin/stdout
• VS Code never re-establishes the connection automatically

The Batch Operation Problem

The batch endpoint (src/tools/work-items.ts#L875-L899) makes a single HTTP PATCH request:

const response = await fetch(`${orgUrl}/_apis/wit/$batch?api-version=${batchApiVersion}`, {
  method: "PATCH",
  headers: { ... },
  body: JSON.stringify(body),
});

If this request is interrupted:

• The async operation never resolves
• The server may enter an inconsistent state
• No cleanup/recovery logic exists

Proposed Solutions

1. Add Heartbeat/Keepalive Mechanism

Implement a periodic heartbeat to detect dead connections and trigger recovery:

// In index.ts or transport layer
let lastHeartbeat = Date.now();
const HEARTBEAT_INTERVAL = 30000; // 30 seconds

setInterval(() => {
  if (Date.now() - lastHeartbeat > HEARTBEAT_INTERVAL * 2) {
    logger.error('Heartbeat timeout - connection may be dead');
    process.exit(1); // Clean exit allows VS Code to restart
  }
}, HEARTBEAT_INTERVAL);

// Update lastHeartbeat on each successful message
transport.onMessage(() => {
  lastHeartbeat = Date.now();
});

2. Add Batch Operation Timeout and Chunking

For src/tools/work-items.ts batch operations:

const BATCH_TIMEOUT_MS = 60000; // 60 second timeout
const MAX_BATCH_SIZE = 25; // Smaller chunks to prevent timeouts

async ({ updates }) => {
  // Chunk large batches
  const chunks = [];
  for (let i = 0; i < updates.length; i += MAX_BATCH_SIZE) {
    chunks.push(updates.slice(i, i + MAX_BATCH_SIZE));
  }
  
  const results = [];
  for (const chunk of chunks) {
    const controller = new AbortController();
    const timeout = setTimeout(() => controller.abort(), BATCH_TIMEOUT_MS);
    
    try {
      const response = await fetch(url, {
        ...options,
        signal: controller.signal,
        body: JSON.stringify(buildBody(chunk)),
      });
      results.push(await response.json());
    } catch (error) {
      if (error.name === 'AbortError') {
        throw new Error(`Batch operation timed out after ${BATCH_TIMEOUT_MS}ms`);
      }
      throw error;
    } finally {
      clearTimeout(timeout);
    }
  }
  
  return results;
}

3. Graceful Shutdown Handler

Add signal handlers to ensure clean shutdown:

// In index.ts
process.on('SIGTERM', () => {
  logger.info('Received SIGTERM, shutting down gracefully');
  server.close().then(() => process.exit(0));
});

process.on('SIGINT', () => {
  logger.info('Received SIGINT, shutting down gracefully');
  server.close().then(() => process.exit(0));
});

process.on('uncaughtException', (error) => {
  logger.error('Uncaught exception', { error });
  process.exit(1); // Clean exit allows reconnection
});

4. Connection Health Check Endpoint

Add a lightweight health check that clients can call:

server.tool(
  'mcp_health_check',
  'Check MCP server health and connection status',
  {},
  async () => {
    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          status: 'healthy',
          uptime: process.uptime(),
          memoryUsage: process.memoryUsage(),
          timestamp: new Date().toISOString(),
        }, null, 2)
      }]
    };
  }
);

Workaround (Current)

Until fixed, users must use VS Code's MCP Server Manager:

1. Press Ctrl+Shift+P
2. Type "MCP: List Servers"
3. Select the "ado" server
4. Click "Start Server" (or "Stop" then "Start")

This properly cleans up the stdio pipe and establishes a fresh connection.

Impact

• Frequency: Occurs whenever batch operations are interrupted
• Severity: Complete loss of MCP functionality until manual recovery
• User Impact: Disrupts workflow, causes data loss if updates partially applied
• Agent Impact: AI agents (Copilot) cannot self-recover, require user intervention

Additional Context

From docs/TROUBLESHOOTING.md and CONTRIBUTING.md:

MCP servers use stdio to communicate with the client. Logs must never appear in stdout (which would break the protocol contract)

The stdio transport is inherently fragile for long-running operations. Consider offering an alternative HTTP/SSE transport for production use cases.

Related Files

• src/index.ts - Main entry, transport setup
• src/tools/work-items.ts - Batch update implementation
• src/logger.ts - Logger configuration

---

Labels

• bug
• transport
• stability
• batch-operations

---

Issue prepared: January 31, 2026
Prepared by: GitHub Copilot (Claude Opus 4.5) with user collaboration

[danhellem]

We have thousands of users actively using this MCP Server, and this is the first time this issue has been reported. We’ll keep the issue open for a couple of weeks to monitor whether others encounter the same problem, but we don’t expect to prioritize work on it unless we see broader impact or additional reports.