Skip to content

[FEATURE] Categorize live MCP startup failures (credentials vs timeout vs config) #214

@hello-args

Description

@hello-args

Summary

Live MCP scans that fail to start often show a generic "MCP SERVER FAILED TO START" panel without actionable categorization — or fall through to MCPProbeError when stderr patterns don't match. multi-server MCP repositories live scans with missing SSO credentials are hard to diagnose: operators can't tell env/config issue from MCTS bug from timeout.

Infrastructure for categorization exists (startup_errors.py) but coverage is incomplete and not always reached.


Problem

Live scan failure modes in validation:

Category Example cause User needs
Missing credentials SSO_ENV, API tokens Set env / use --env-file (F9)
Import error wrong Python, missing module Fix venv / -m module (C12)
Process exit bad command path Fix .mcp.json launch args
Timeout server hang Increase timeout, check stderr
Unknown unmatched stderr Full stderr tail

Proposed solution

Parse stderr; categorize credentials/health/timeout.

Acceptance Criteria

  • ifd credential failure → MISSING_CREDENTIALS category
  • ModuleNotFoundError → IMPORT_ERROR with venv suggestion
  • Timeout → TIMEOUT with stderr tail
  • Unknown failures include stderr tail in panel
  • JSON error schema documented
  • Pairs with F9 --env-file suggestion in message

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions