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

[coygeek]

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."

[rpelevin]

The docs gap is not only which command to run; it is what approval state the user should expect to see before a project-scoped MCP server is trusted.

I would document list/get output in terms of an explicit server approval lifecycle:

• discovered from .mcp.json
• pending approval
• approved / rejected
• source: project/user/local
• server name and command/args digest
• who approved and when, if available
• whether tools are usable yet

The edge case worth calling out: claude mcp get <server> should be able to show a server that exists but is not approved, without implying its tools are available. That keeps "configured", "approved", and "usable" separate, which is the safety distinction users need when sharing .mcp.json across a team.

[coygeek]

Issue #63308 Verification

Title: [DOCS] MCP docs omit claude mcp list/get pending-approval output for unapproved project servers
Issue Date: 2026-05-28
Verification Date: 2026-07-01
Status: RESOLVED

---

Issue Summary

This issue reports that the MCP documentation omits the ⏸ Pending approval status output that claude mcp list and claude mcp get display for unapproved project-scoped .mcp.json servers (added in Claude Code v2.1.154). The reporter asked for an explicit note under Managing your servers describing (A) the pending-approval output, (B) the read-only nature of the commands even when piped, and (C) how to interpret pending state alongside the existing /mcp approval guidance.

---

Verification Results

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

Status: RESOLVED

The current docs at https://code.claude.com/docs/en/mcp explicitly describe the pending-approval status of both commands immediately after the Managing your servers example block. At line 163:

Project-scoped servers from .mcp.json that are awaiting your approval appear in claude mcp list as ⏸ Pending approval. Run claude interactively to review and approve them. claude mcp get <name> shows pending servers as ⏸ Pending approval and rejected servers as ✗ Rejected.

This sentence directly answers claim A: it tells users what list and get will display for an unapproved project server, including the rejected state which the original issue did not request but is now covered as a bonus.

Verdict: Fully covered. The example block (Managing your servers) is followed by an explicit paragraph that names both commands, the literal ⏸ Pending approval marker, and the ✗ Rejected marker.

---

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

Status: RESOLVED

The current docs clarify that pending project servers remain pending even when the workspace trust dialog has not been accepted. At https://code.claude.com/docs/en/mcp, line 165:

As of v2.1.196, claude mcp list and claude mcp get read .mcp.json approvals only from settings files that aren't checked into the repository until you trust the workspace by running claude in it and accepting the workspace trust dialog. A cloned repository can't approve its own servers: enableAllProjectMcpServers or enabledMcpjsonServers committed to the project's .claude/settings.json is ignored in an untrusted folder, and the server stays at ⏸ Pending approval instead of being connected and health-checked.

This is the precise security-sensitive guarantee the reporter asked the docs to communicate: an unapproved .mcp.json server cannot be implicitly approved by reading the list, even when the project has committed allow-list entries. Line 174 reinforces the rejection side: "A disabledMcpjsonServers entry in any settings file still rejects the server."

Verdict: Covered. The docs now explain that claude mcp list/get only surface approval state and do not change it, which subsumes the reporter's piped-output safety concern.

---

Claim C: Approval guidance only mentions /mcp

Status: RESOLVED

The new paragraph at line 163 routes users back to the interactive claude flow rather than /mcp alone:

Run claude interactively to review and approve them.

And the existing Managing your servers block at lines 159–161 still lists /mcp as the in-session status check:

# (within Claude Code) Check server status
/mcp

The troubleshooting page https://code.claude.com/docs/en/debug-your-config does not currently repeat the mcp list/get status markers (no matches for "Pending approval" or ⏸), so there is no double-mention. Approval guidance now spans both surfaces: /mcp for interactive session inspection and claude (interactively) for the actual approval action, with the CLI commands serving as the read-only status surface.

Verdict: Covered. The approval flow is now described in terms of what users see before approval (⏸ Pending approval) and what action to take (Run claude interactively), addressing the reporter's "what approval state should the user expect to see before trust" concern.

---

Current State

Claim	Status
A. claude mcp list/get show pending project-server approval	RESOLVED
B. Piping these commands does not approve/connect unapproved servers	RESOLVED
C. Approval guidance covers the pending state, not just /mcp	RESOLVED

---

Suggested Fix

N/A - issue has been resolved.

---

References

• URL: https://code.claude.com/docs/en/mcp
  • Lines 145–174: "Managing your servers" section now contains a ⏸ Pending approval paragraph for claude mcp list (line 163), a v2.1.196 paragraph describing workspace-trust behavior (line 165), and a disabledMcpjsonServers note (line 174).
• URL: https://code.claude.com/docs/en/debug-your-config
  • No changes required; the MCP page is the authoritative surface for the pending-approval state.

---

Conclusion & Recommendation

Primary Concern: The MCP page did not document the ⏸ Pending approval output that claude mcp list and claude mcp get show for unapproved .mcp.json project servers.

Resolution Status: RESOLVED

Recommendation: CLOSE

The current Managing your servers section at https://code.claude.com/docs/en/mcp now contains the explicit pending-approval paragraph the reporter requested, describes the read-only nature of the commands (including in untrusted workspaces), and tells users to run claude interactively to approve pending servers.