Feature Request: Include error details in mcpServerStatus() response

Resolved 💬 2 comments Opened Dec 23, 2025 by leekuo Closed Dec 23, 2025

Summary

When using mcpServerStatus() from the Agent SDK, failed MCP server connections only return status: 'failed' without any error details. This makes it difficult to diagnose why an MCP server failed to connect.

Current Behavior

const statusQuery = query({
  prompt: '',
  options: {
    mcpServers: { /* ... */ },
    stderr: (msg: string) => {
      // Error details may appear here, but are not associated with the server
      console.log(msg);
    },
  },
});

const mcpStatus = await statusQuery.mcpServerStatus();
console.log(mcpStatus);

Output:

[
  {
    "name": "tech-assistant-mcp",
    "status": "connected",
    "serverInfo": {
      "name": "dxai",
      "version": "1.0.0"
    }
  },
  {
    "name": "looperpro-mcp-server",
    "status": "failed"
  }
]

The McpServerStatus type is currently:

type McpServerStatus = {
    name: string;
    status: 'connected' | 'failed' | 'needs-auth' | 'pending';
    serverInfo?: {
        name: string;
        version: string;
    };
};

Expected Behavior

When a server fails to connect, include the error message/details in the response:

type McpServerStatus = {
    name: string;
    status: 'connected' | 'failed' | 'needs-auth' | 'pending';
    serverInfo?: {
        name: string;
        version: string;
    };
    error?: string;  // Error message when status is 'failed'
};

Expected output:

[
  {
    "name": "tech-assistant-mcp",
    "status": "connected",
    "serverInfo": {
      "name": "dxai",
      "version": "1.0.0"
    }
  },
  {
    "name": "looperpro-mcp-server",
    "status": "failed",
    "error": "Connection refused: ECONNREFUSED 127.0.0.1:3000"
  }
]

Use Case

We're building a VS Code extension that integrates with MCP servers. When displaying MCP server status to users, we need to show meaningful error messages for failed connections so they can troubleshoot issues (e.g., server not running, authentication failed, network issues, etc.).

Currently, the error details are only available via the stderr callback, but they're not associated with specific servers and appear asynchronously before mcpServerStatus() resolves, making it difficult to correlate errors with specific server failures.

Environment

  • @anthropic-ai/claude-agent-sdk version: latest
  • Node.js version: 20.x

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗