Skip to content

feat: structured MCP error codes and failure diagnostics (closes #6352)#6529

Open
vakrahul wants to merge 1 commit intoaden-hive:mainfrom
vakrahul:fix/mcp-structured-errors
Open

feat: structured MCP error codes and failure diagnostics (closes #6352)#6529
vakrahul wants to merge 1 commit intoaden-hive:mainfrom
vakrahul:fix/mcp-structured-errors

Conversation

@vakrahul
Copy link
Contributor

@vakrahul vakrahul commented Mar 16, 2026

feat: Structured MCP error codes & failure diagnostics (closes #6352)

Summary

Implements structured error handling across MCP registry operations so
users can quickly self-diagnose issues instead of seeing raw Python
tracebacks.

Changes

New: core/framework/runner/mcp_errors.py

  • MCPErrorCode enum with all 7 required error codes:
    MCP_INSTALL_FAILED, MCP_AUTH_MISSING, MCP_CONNECT_TIMEOUT,
    MCP_TOOL_NOT_FOUND, MCP_PROTOCOL_MISMATCH,
    MCP_VERSION_CONFLICT, MCP_HEALTH_FAILED
  • MCPError base class enforcing What/why/fix message format
  • Subclasses: MCPToolNotFoundError, MCPAuthError,
    MCPInstallError, MCPConnectTimeoutError,
    MCPProtocolMismatchError, MCPVersionConflictError,
    MCPHealthCheckError

Modified: core/framework/runner/mcp_client.py

  • Replaced raw ValueError in call_tool with MCPToolNotFoundError
  • Added [Server: X] [Transport: Y] context to all tool call
    error paths in _call_tool_stdio_async and _call_tool_http

Modified: core/framework/runner/tool_registry.py

  • register_mcp_server now emits structured log on both success
    and failure: {server, status, tools_loaded, skipped_reason}

New: core/tests/test_mcp_errors.py

  • 5 unit tests — all passing on Ubuntu and Windows CI

Requirements Covered

ID Requirement Status
DX-1 Structured error codes
DX-2 What/why/fix error messages
DX-4 Structured startup logging
DX-5 Server context in tool call errors

Note

mcp_registry.py does not yet exist in the codebase — it is being
created in #6349 by @Antiarin.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[MCP Registry] Structured error codes & failure diagnostics (DX)

1 participant