[DOCS] MCP docs omit `claude mcp list/get` pending-approval output for unapproved project servers

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/mcp

Section/Topic

Managing your servers and Project scope approval behavior for .mcp.json servers

Current Documentation

The MCP page lists claude mcp list and claude mcp get as server-management commands:

Once configured, you can manage your MCP servers with these commands: # List all configured servers claude mcp list # Get details for a specific server claude mcp get github

The project-scope section explains that .mcp.json servers require approval:

Project-scoped servers enable team collaboration by storing configurations in a .mcp.json file at your project's root directory.

For security reasons, Claude Code prompts for approval before using project-scoped servers from .mcp.json files. If you need to reset these approval choices, use the claude mcp reset-project-choices command.

The troubleshooting page also points users to /mcp for approval state:

Run /mcp to see every configured server, its connection status, and whether you have approved it for the current project.

Project-scoped servers in .mcp.json require a one-time approval. If the prompt was dismissed, the server stays disabled until you approve it from /mcp.

What's Wrong or Missing?

Claude Code v2.1.154 changed claude mcp list and claude mcp get so unapproved .mcp.json servers show as ⏸ Pending approval instead of being auto-approved and connected when command output is piped.

The current docs do not tell users that:

A. claude mcp list and claude mcp get report pending project-server approval

The CLI command list shows how to run list and get, but it does not describe their status output or say that unapproved project-scoped servers appear as pending approval.

B. Piping the command output should not approve or connect unapproved .mcp.json servers

The security-sensitive behavior is that observing MCP status in a pipeline should remain read-only. Users who script claude mcp list or claude mcp get need to know that these commands now preserve approval state and surface Pending approval instead of implicitly approving a project server.

C. Approval guidance only mentions /mcp

The current approval guidance says users can approve dismissed project servers from /mcp, but it does not explain what the non-interactive CLI commands show before approval or how to interpret that pending state.

Suggested Improvement

Add a short note under Managing your servers after the claude mcp list / claude mcp get examples:

Project-scoped servers from .mcp.json require one-time approval before Claude Code connects to them. Until approved, claude mcp list and claude mcp get <name> show the server as ⏸ Pending approval. These commands do not approve or connect pending project servers, including when their output is piped or redirected. Approve the server from /mcp when you trust the project configuration.

Also cross-reference this from the Project scope section after the existing approval paragraph.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/mcp | Primary MCP setup and claude mcp list / claude mcp get command documentation |
| https://code.claude.com/docs/en/debug-your-config | Troubleshooting guidance for project .mcp.json approval currently points only to /mcp |
| https://code.claude.com/docs/en/headless | Related context for piped/non-interactive Claude Code workflows |

Total scope: 3 pages affected

Version context: Claude Code v2.1.154 changelog entry: "claude mcp list/get now show unapproved .mcp.json servers as ⏸ Pending approval instead of auto-approving and connecting when output is piped."