Phase 5-A: Backend MCP Server Health Endpoint #53

New Issue

Open

opened 2026-05-24 16:55:20 -05:00 by null · 0 comments

null commented

2026-05-24 16:55:20 -05:00

Owner

Source plan: /home/kaspa/.claude/plans/with-our-backend-created-precious-owl.md

Feature context: Feature 5: MCP Server Health Panel

Scope

Phase 5-A — Backend

Summary

Extend GET /claude-code/config (or add GET /claude-code/mcp-servers) to parse the mcpServers block from ~/.claude/settings.json and attempt a connectivity check for HTTP-transport servers.

Problem

MCP servers are configured in settings.json but completely invisible after setup. Users have no way to see which servers are running without checking logs manually.

Affected area

Backend service: Claude Code reader / config scanner
API: /claude-code

Affected files

backend/app/services/claude_code_reader.py — add get_mcp_servers() function (reads + probes)
backend/app/api/claude_code.py — add new route or extend config route
backend/app/schemas/claude_code.py — add McpServerRead, McpServersResponse schemas

Affected routes or endpoints

GET /api/v1/claude-code/mcp-servers

Expected behavior

Returns list of MCP server entries:

[
  {
    "name": "github",
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "status": "unknown"
  },
  {
    "name": "my-http-server",
    "transport": "http",
    "url": "http://localhost:3001",
    "status": "reachable"
  }
]

stdio transport: status always "unknown" (can't probe without spawning process)
http/sse transport: attempt GET {url}/health or HEAD {url} with 2s timeout; status = "reachable" or "unreachable"
Parses both settings.json top-level mcpServers and any projects-scoped overrides (flatten, deduplicate by name)

Steps to reproduce (acceptance criteria)

GET /api/v1/claude-code/mcp-servers returns entries matching settings.json
HTTP servers show reachable or unreachable based on actual connectivity
stdio servers show unknown
Empty array returned if no MCP servers configured

Source plan: `/home/kaspa/.claude/plans/with-our-backend-created-precious-owl.md` Feature context: **Feature 5: MCP Server Health Panel** ## Scope ### Phase 5-A — Backend #### Summary Extend `GET /claude-code/config` (or add `GET /claude-code/mcp-servers`) to parse the `mcpServers` block from `~/.claude/settings.json` and attempt a connectivity check for HTTP-transport servers. #### Problem MCP servers are configured in `settings.json` but completely invisible after setup. Users have no way to see which servers are running without checking logs manually. #### Affected area - Backend service: Claude Code reader / config scanner - API: `/claude-code` #### Affected files - `backend/app/services/claude_code_reader.py` — add `get_mcp_servers()` function (reads + probes) - `backend/app/api/claude_code.py` — add new route or extend config route - `backend/app/schemas/claude_code.py` — add `McpServerRead`, `McpServersResponse` schemas #### Affected routes or endpoints - `GET /api/v1/claude-code/mcp-servers` #### Expected behavior Returns list of MCP server entries: ```json [ { "name": "github", "transport": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "status": "unknown" }, { "name": "my-http-server", "transport": "http", "url": "http://localhost:3001", "status": "reachable" } ] ``` - `stdio` transport: status always `"unknown"` (can't probe without spawning process) - `http`/`sse` transport: attempt `GET {url}/health` or `HEAD {url}` with 2s timeout; status = `"reachable"` or `"unreachable"` - Parses both `settings.json` top-level `mcpServers` and any `projects`-scoped overrides (flatten, deduplicate by name) #### Steps to reproduce (acceptance criteria) 1. `GET /api/v1/claude-code/mcp-servers` returns entries matching `settings.json` 2. HTTP servers show `reachable` or `unreachable` based on actual connectivity 3. `stdio` servers show `unknown` 4. Empty array returned if no MCP servers configured ---