[FEATURE] Add scope information to `claude mcp list` output

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Summary

The claude mcp list command should display the scope (local/project/user) for each MCP server to help developers understand context loading behavior and troubleshoot token usage fluctuations.

Problem Description

Current Behavior

$ claude mcp list
Checking MCP server health...

metamcp-rag: node /path/to/server/dist/index.js - ✓ Connected

Issues This Creates

1. Unclear scope context: Users cannot determine if an MCP server is configured at local, project, or user scope
2. Debugging difficulties: When MCP tools appear/disappear in /context, users cannot understand why
3. Token usage confusion: Context window fluctuations are unexplained without scope visibility
4. Team collaboration problems: No way to distinguish between personal vs. shared (project-scoped) servers

Real-World Impact

User Experience Issue

I experienced significant confusion when my context usage fluctuated dramatically:

• 79k tokens (40%): Full MCP toolset loaded (~59.4k MCP tools + project files)
• 36k tokens (18%): MCP tools unloaded, project files present
• 20k tokens (10%): Minimal context, no MCP tools

Without scope information, it was impossible to understand this was due to directory-based MCP loading.

Current Workarounds

• Manually checking for .mcp.json files in directories
• Guessing scope based on where tools appear/disappear
• Trial and error to understand MCP server availability

Proposed Solution

Enhanced claude mcp list Output

$ claude mcp list
Checking MCP server health...

metamcp-rag (user): node /path/to/server/dist/index.js - ✓ Connected
filesystem (project): npx @modelcontextprotocol/server-filesystem /project/path - ✓ Connected
token-analyzer (local): node /path/to/local/server.js - ✓ Connected

Optional: Verbose Flag

$ claude mcp list --verbose
Checking MCP server health...

metamcp-rag
  Scope: user
  Command: node /path/to/server/dist/index.js
  Status: ✓ Connected
  Available in: all projects

filesystem
  Scope: project
  Command: npx @modelcontextprotocol/server-filesystem /project/path
  Status: ✓ Connected
  Available in: current project only
  Config: .mcp.json

token-analyzer
  Scope: local
  Command: node /path/to/local/server.js
  Status: ✓ Connected
  Available in: current project (private)

Technical Context

MCP Scope Hierarchy

Based on the documentation:

1. Local scope (highest priority): Private to current project
2. Project scope: Shared via .mcp.json, checked into version control
3. User scope (lowest priority): Available across all projects

Related Documentation

• Project-scoped MCP servers
• Scope hierarchy and precedence

Implementation Considerations

Data Already Available

The scope information must already be available internally since:

• Claude Code correctly loads/unloads servers based on directory context
• Different scopes have different precedence rules
• Project servers require approval prompts

Minimal UX Impact

• Default output: Simple (scope) addition maintains current format
• Verbose flag: Optional detailed view for debugging
• Backward compatibility: Existing scripts parsing output remain functional

Benefits

For Individual Developers

• Understand context changes: Why MCP tools appear/disappear between directories
• Debug token usage: Identify what's consuming context window space
• Manage server configurations: Know which servers are personal vs. shared

For Teams

• Collaboration clarity: Distinguish personal tools from team-shared servers
• Onboarding efficiency: New team members understand available MCP tools
• Configuration management: Audit which servers are project-scoped vs. personal

Alternative Solutions

Alternative Solutions Considered

1. Separate command (claude mcp list-scopes)
2. Configuration file inspection: Requires users to manually check .mcp.json and settings
3. Documentation updates: Doesn't solve runtime visibility

Priority

Medium - Would be very helpful

Feature Category

MCP server integration

Use Case Example

_No response_

Additional Context

_No response_