Feature Request: CLI command to list available MCP tools and servers

• Type: Enhancement
• Areas: area:mcp, area:tools, area:tui, area:core
• Labels suggested: enhancement, area:mcp, area:tools, area:tui

Summary

Add first-class CLI commands to enumerate and inspect currently available MCP tools and servers across:

• the active session,
• specific sub-agents,
• specific MCP servers.

This improves discoverability, debugging, permission verification, documentation, and automation for users managing many tools/servers.

Motivation / Problem

Today there is no reliable, user-facing CLI to list the exact MCP tools that Claude Code can see and use at a given moment. This causes pain points:

• Hard to verify tool availability/permissions for a session or a sub-agent (e.g., "Is mcp__desktop-commander__search_code actually exposed and allowed right now?").
• Troubleshooting "tool not found"/permission issues is guessy (system message doesn't contain actual tools field #3069, [BUG] "MCP Tools Not Available in Conversation Interface Despite Successful Connection" #2682).
• Creating internal docs/automation (e.g., generating a tools matrix per project/agent) requires manual spelunking or parsing logs.
• When tool sets change dynamically (connect/disconnect, permission changes), there's no single command to re-check the current truth (Capture MCP Tools Changed notifications - notifications/prompts/list_changed notifications #4118).

I'm contributing locally maintained docs (see docs/complete-mcp-tools-list.md) but this is static and specific to my environment. A built-in CLI would be far more reliable and broadly useful.

Proposed Solution

Introduce a new set of CLI commands that expose the current MCP topology and tool catalog, with human-friendly and JSON output.

Commands (UX proposal)

1. List tools (global/session)

• claude tools list [--json] [--wide] [--filter <expr>] [--columns <cols>]
• Options:
  • --server <name|pattern> filter by MCP server id/name
  • --agent <subagent-name> filter by sub-agent
  • --permissions [allowed|denied|all] annotate/filter by current permission state
  • --origin include origin server for each tool
  • --schema include a compact input schema summary (e.g., arg names/types, required)
  • --json machine output (see schema below)
  • --ndjson one JSON object per line (stream-friendly)
  • --filter simple text/regex filter across server/agent/tool ids and descriptions
  • --columns choose visible columns in table output
  • --wide include more columns in table output

2. Inspect tool (schema/details)

• claude tools inspect <tool-id> [--json] [--schema] [--examples]
  • Shows full tool definition, input schema, example payloads, origin server, permissions.

3. List MCP servers

• claude mcp servers list [--json]
  • Includes server name, transport, status, tool count, resource count (if applicable).

4. Watch for changes (optional)

• claude tools watch [--json]
  • Subscribes to tool-change notifications if available (Capture MCP Tools Changed notifications - notifications/prompts/list_changed notifications #4118), re-printing deltas (added/removed/changed).

Table Output (examples)

claude tools list --columns server,agent,tool,summary,permissions:

SERVER              AGENT               TOOL                                   SUMMARY                                   PERMISSIONS
desktop-commander   (session)           mcp__desktop-commander__read_file      Read file with offset/length               allowed
desktop-commander   security-auditor    mcp__desktop-commander__search_code    Ripgrep-based code search                  allowed
zen                 code-reviewer       mcp__zen__codereview                   Systematic code review workflow            allowed
notionApi           (session)           mcp__notionApi__API-post-page          Create a Notion page                       denied
...

claude mcp servers list:

SERVER              TRANSPORT    STATUS     TOOLS  RESOURCES
desktop-commander   stdio        connected  18     -
zen                  http         connected  12     -
notionApi           http         connected   15     (resources supported)
slack               http         connected   4      -
...

JSON Output (schema proposal)

claude tools list --json returns:

{
	"timestamp": "2025-08-26T06:31:00Z",
	"sessionId": "abc-123",
	"servers": [
		{
			"name": "desktop-commander",
			"transport": "stdio",
			"status": "connected",
			"tools": [
				{
					"id": "mcp__desktop-commander__read_file",
					"originServer": "desktop-commander",
					"agents": ["(session)", "security-auditor"],
					"summary": "Read file (supports offset/length)",
					"permissions": "allowed",
					"schema": {
						"input": {
							"type": "object",
							"properties": {
								"path": { "type": "string" },
								"offset": { "type": "number" },
								"length": { "type": "number" }
							},
							"required": ["path"]
						}
					}
				}
			]
		}
	]
}

claude tools inspect mcp__desktop-commander__read_file --json returns a single object with full schema, examples (if known), and current permission resolution.

Filtering Examples

• claude tools list --server desktop-commander
• claude tools list --agent security-auditor
• claude tools list --filter "(read|write)"
• claude tools list --permissions denied
• claude tools list --json | jq '.servers[].tools[] | select(.permissions=="allowed") | .id'

Behavior / Semantics

• Read-only introspection: DOES NOT invoke any tool.
• Reflects the current session truth (after all permissions/allowlists are applied).
• Includes sub-agent context if specified (some tools may be hidden/denied per sub-agent).
• Handles dynamic environments: if servers connect/disconnect, list updates accordingly (and watch receives events when available).
• Stable, scriptable output for automation pipelines.

Security, Privacy, and Permissions

• Respect all existing permission models (allowedTools, disallowed-tools, flags, etc.). If a tool is denied, it should show as denied (or be filtered out when requested).
• Redact sensitive data in tool descriptions or server metadata if any could leak (do not show secrets, env vars, tokens).
• The command should not fetch external network resources beyond what's needed for current MCP topology in the running session.

Edge Cases

• Disconnected or failing servers: mark status: disconnected and show reason if known.
• Very large tool sets: support --filter and --columns; JSON + downstream filters recommended.
• Pagination: Desirable for resources ([ENHANCEMENT] MCP Resources Pagination Support for ListMcpResourcesTool #3141). For tools it might be less critical, but consider --limit/--offset to future-proof.
• Headless/CI usage: All commands must be non-interactive and return non-zero exit on internal errors.

Acceptance Criteria

• claude tools list lists all currently available tools for the session by default (table).
• --json produces a machine-consumable structure with server, tool ids, origin, agents, summary, permissions, and an input schema summary.
• --server / --agent / --permissions / --filter are supported.
• claude tools inspect <tool-id> prints complete schema and origin.
• claude mcp servers list shows current servers with status and basic counts.
• Does not invoke tools, respects permissions, no secrets leaked.
• Tested on macOS/Linux/Windows environments with both stdio and HTTP MCP servers.

Related Issues (context / adjacency)

• [FEATURE REQUEST] Add slash command to show tool usage summary #5334 Add slash command to show tool usage summary (usage vs. enumeration; complementary)
• system message doesn't contain actual tools field #3069 system message doesn't contain actual tools field (discoverability/visibility)
• Capture MCP Tools Changed notifications - notifications/prompts/list_changed notifications #4118 Capture MCP Tools Changed notifications (would integrate nicely with tools watch)
• [Feature Request] Add MCP Server and Tool Definition Metrics to Statusline JSON #5511 Add MCP Server and Tool Definition Metrics to Statusline JSON (diagnostics/visibility)
• [ENHANCEMENT] MCP Resources Pagination Support for ListMcpResourcesTool #3141 MCP Resources Pagination Support for ListMcpResourcesTool (resource listing; analogous patterns)
• [BUG] "MCP Tools Not Available in Conversation Interface Despite Successful Connection" #2682 MCP tools not available in UI despite connection (debugging aid)
• Is claude mcp serve meant to also serve its own configured MCP tools? #631 Is claude mcp serve meant to also serve its own configured MCP tools? (server semantics)

Implementation Notes (high-level)

• Source-of-truth should be the internal MCP manager that holds active server connections and tool registries (post-permission resolution).
• Reuse any existing structs used to build system messages, but ensure they reflect the live, current set of tools (addressing system message doesn't contain actual tools field #3069).
• Table rendering mirrors existing CLI styling (column config, wide mode).
• JSON output should be versioned (version: 1) to allow evolution.
• Consider emitting list_changed notifications to power tools watch as a follow-up.

Testing Plan

• Unit: formatters, filters, permission annotation, JSON schema shape.
• Integration: with stdio servers (e.g., Desktop Commander), HTTP servers (e.g., Playwright/Notion/Slack), and environments with sub-agents.
• E2E: start/stop servers, toggle permissions, observe tools list reflecting changes.
• Cross-platform: macOS, Linux, Windows.

Alternatives Considered

• Parsing verbose debug logs — brittle and unfriendly.
• Exposing tools via an ad-hoc API only — non-CLI users blocked.
• Relying on editor UI only — excludes headless/CI usage.

Contributor Availability

I'm willing to draft an implementation and open a PR if maintainers agree on:

• command names/flags,
• JSON schema shape,
• where to integrate within the CLI codebase.

If maintainers prefer a different naming (e.g., claude mcp tools list instead of claude tools list), I'm happy to align.

Generated from a real need in documenting and validating tools locally (docs/complete-mcp-tools-list.md). Happy to iterate on this proposal.