Feature: Machine-readable MCP server state file for programmatic discovery

Problem

Custom cloud MCP connectors (added via claude.ai account settings) are invisible to any tool that tries to discover MCP servers by parsing local config files.

Local config files and what they contain:

| File | Contains |
|------|----------|
| ~/.claude.json → mcpServers | Only locally configured servers (e.g. stdio-based) |
| ~/.claude/mcp-needs-auth-cache.json | Only cloud servers requiring OAuth (Gmail, Calendar) |
| ~/.claude/settings.json | No MCP server list |
| .mcp.json (project) | Only project-scoped local servers |

What's missing: Cloud custom connectors (user-added URLs in claude.ai settings, no OAuth required) exist in none of these files. The only way to get the complete server list is:

claude mcp list

This means any IDE integration, terminal wrapper, or dev tool that needs to know which MCP servers are available must spawn a subprocess and parse CLI stdout. This is fragile, slow, and breaks when output format changes.

Proposal

Claude Code maintains a machine-readable JSON state file with all connected MCP servers, e.g.:

~/.claude/mcp-servers-state.json

Example structure:

{
  "servers": [
    {
      "name": "n8n",
      "type": "local",
      "transport": "stdio",
      "status": "connected",
      "config_source": "user"
    },
    {
      "name": "claude.ai Gmail",
      "type": "cloud",
      "url": "...",
      "auth": "oauth",
      "status": "waiting"
    },
    {
      "name": "claude.ai Supaskills",
      "type": "cloud",
      "url": "https://www.supaskills.ai/mcp",
      "auth": "none",
      "status": "connected"
    }
  ],
  "updated_at": "2026-03-14T12:00:00Z"
}

Use Cases

1. IDE integrations (VS Code, JetBrains) can show MCP server status without spawning CLI
2. Custom terminal UIs (e.g. wrappers around Claude Code) can discover all servers programmatically
3. Monitoring/health checks can watch the file for status changes
4. MCP server developers can verify their server is connected without manual CLI checks

Alternatives Considered

• Parse claude mcp list stdout: Works but fragile, requires subprocess spawn, slow
• claude mcp list --json flag: Better than parsing text, but still requires subprocess. Would be a good intermediate step if a state file is too much.

Environment

• Claude Code v2.1.76
• macOS (but applies to all platforms)