Skip to content

[Feature/Bug] Graceful fallback when MCP config file is invalid — service should not fail to start #474

@EmotionalAmo

Description

@EmotionalAmo

Summary

When the MCP configuration file (mcp.json / mcp.yaml) contains errors
(syntax errors, missing required fields, invalid JSON, etc.), the service
fails to start entirely instead of gracefully disabling MCP features.

Current Behavior

The load_mcp_config() and validate_config() functions in omlx/mcp/config.py
raise exceptions for config problems:

  • json.JSONDecodeError — malformed JSON
  • ValueError — missing required fields (e.g., command for stdio, url for SSE)
  • FileNotFoundError — explicitly specified config file path doesn't exist

The init_mcp() function in omlx/server.py currently only catches ImportError
(missing MCP SDK). Config-level exceptions propagate upward and crash the startup.

Expected Behavior

The server should start successfully even when the MCP config file is broken.
MCP features should simply be disabled with a clear error message logged.

This is consistent with how oMLX already handles the missing MCP SDK:

# Existing graceful handling for missing SDK (init_mcp in server.py)
except ImportError:
    logger.info("MCP SDK not installed. MCP features disabled.")
    return

The same pattern should apply to config errors.

Proposed Fix

Extend the exception handling in init_mcp() to cover config parsing/validation errors:

except (json.JSONDecodeError, ValueError, FileNotFoundError) as e:
    logger.error(
        f"Failed to load MCP config: {e}. "
        "MCP features disabled. Please fix your MCP config file and restart."
    )
    return  # Fallback: server starts without MCP

Steps to Reproduce

  1. Create an invalid mcp.json (e.g., malformed JSON or missing command field for a stdio server)
  2. Start oMLX with --mcp-config /path/to/broken/mcp.json
  3. Observe: server fails to start

Impact

  • Users who accidentally introduce a typo in their MCP config lose access to the
    entire oMLX service, not just MCP tools
  • MCP is an optional feature — its config errors should never block core server startup

Additional Enhancement (Optional)

Expose the MCP config error in the admin dashboard or /health API endpoint
so users can easily diagnose the issue without digging through logs.


Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions