Improve error handling when MCP servers fail to start

[JeanMertz]

MCP server startup failures currently produce cryptic error messages that don't help users diagnose the root cause. When servers fail due to missing environment variables or other configuration issues, users receive unhelpful messages like "IO error: connection closed: initialize response" instead of actionable feedback.

Context

Currently, when an MCP server fails to start (for example, if the kagimcp MCP server fails because the required KAGI_API_KEY environment variable is missing), the error handling provides minimal diagnostic information. The create_client function in crates/jp_mcp/src/client.rs silently filters missing environment variables and attempts to spawn the server process, but when the server exits due to missing configuration, the connection failure during initialization results in generic error messages.

According to the Kagi MCP server documentation and similar MCP servers, many require specific environment variables to function properly. When these are missing, servers typically exit immediately with their own error messages, but these are lost in the current error handling approach.

Alternatives

Users can manually debug MCP server issues by running the server commands directly to see their error output, but this requires technical knowledge and doesn't provide a seamless experience. We could also implement more sophisticated process monitoring to capture stderr output, but the proposed solution focuses on proactive validation and clearer error reporting.

Proposed Implementation

Enhance the create_client function in crates/jp_mcp/src/client.rs to:

1. Validate required environment variables: Before attempting to start the server, check if all configured environment variables are available and non-empty
2. Capture server stderr output: Modify the TokioChildProcess setup to capture stderr from the spawned process for better error reporting
3. Improve error messages: Replace generic "connection closed" errors with specific diagnostic information about missing environment variables and server startup failures
4. Add server-specific validation: For well-known servers like kagimcp, provide specific guidance about required configuration

The error handling should distinguish between configuration issues (missing env vars) and actual connection problems, providing users with actionable error messages.

Tasks

• Add environment variable validation before server startup in create_client function
• Modify TokioChildProcess configuration to capture stderr output from MCP servers
• Create specific error variants in crates/jp_mcp/src/error.rs for configuration validation failures
• Update error messages to provide actionable guidance for common MCP server configuration issues
• Add integration tests for MCP server startup error scenarios

Resources

• https://github.com/dcdpr/jp/blob/main/crates/jp_mcp/src/client.rs#L207-L230
• https://github.com/dcdpr/jp/blob/main/crates/jp_mcp/src/error.rs
• https://github.com/dcdpr/jp/blob/main/.jp/mcp/servers/kagi.json