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

[adalgu]

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.

[adalgu]

Additional context: aware of interactive /agents but need non-interactive discoverability

• We are aware that in interactive mode the /agents command can surface agent/tool information (and it is useful).
• However, real-world workflows often require non-interactive authoring and validation of sub-agents and their tool assignments (CI, headless scripts, pre-commit hooks).
• When assigning tools to sub-agents in frontmatter, we need an authoritative reference for exact tool IDs and availability without entering interactive mode.
• Switching into interactive mode just to inspect current tools is inefficient and brittle for automation; it does not fit PR validation or batch script use.
• A CLI list/inspect fills this gap and enables:
  • repeatable checks in CI (fail if a referenced tool does not exist or is currently denied),
  • docs generation for subagent tool matrices,
  • faster authoring with shell completion/grepping,
  • permission audits without interactive sessions.

This is complementary to /agents; it does not replace it.

[coygeek]

+1, this is an excellent and very well-thought-out proposal.

The lack of a non-interactive way to discover available tools is a significant hurdle for automation and for maintaining complex configurations, especially in a team setting.

Currently, the best we have is claude mcp list, which confirms servers are connected but gives no insight into the tools they provide. As you noted, the interactive /mcp and /agents commands are great for manual inspection but are a dead-end for any kind of scripting or CI/CD validation.

A prime example where your proposed claude tools list --json would be a game-changer is for validating our project's sub-agent configurations. We define sub-agents in .claude/agents/ and specify their allowed tools in the frontmatter, like this:

---
name: security-auditor
description: Reviews code for security issues using static analysis tools.
tools: mcp__sentry__get_issue, Read, Grep
---
...

Right now, a typo in a tool name like mcp__sentry__get_issue is only caught at runtime. With your proposed command, we could easily build a pre-commit hook or a CI step to validate that every tool listed in our agent definitions is actually available and permitted in the current environment.

# Imagined CI script
AGENT_TOOLS=$(grep -r "tools:" .claude/agents | sed 's/tools: //g' | tr ',' '\n' | sort -u)
AVAILABLE_TOOLS=$(claude tools list --json | jq -r '.servers[].tools[].id')

# Compare the lists and fail the build if any agent tool is not available
...

This would make our agent configurations far more robust.

Your proposal for claude tools inspect <tool-id> is also brilliant for debugging and for anyone trying to build integrations on top of the Claude Code SDK.

I support this feature request. It aligns perfectly with the "Unix philosophy" mentioned in the overview docs by making the tool more composable and scriptable.

[allisoneer]

Yes this would be lovely. The alternative would be an equivalent of allowedTools that is actually a white list of availability and not permissions. Currently there is no way to replicate the agent/task functionality (whitelist a specific amount of tools) without hard-coding the default claude tools and already knowing all available mcp tools.

Claude code already has the logic internally. Both for the mcp serve functionality and the agents functionality. We just need it exposed.

Oh wait, that's a potential workaround for all of us. We can:

1. run claude mcp serve and extract all regular tools from the tools/list mcp request.
2. run claude mcp list and extract all the mcp tools from each of their tools/list.

I still support this feature request but I'm happy now. I know how to get unstuck.

FWIW, I'm like >90% positive claude mcp serve showed the list of mcp tools in addition to internal for a couple days/weeks previously. The change to only show internal ones happened semi-recently I think (+/- 1-2 months). Having a single --include-mcp to act as a redirection (like it potentially used to) would solve my problems too. Less eloquently than the above comments, but with much less code modifications needed.

Oh wow! The PR is beautiful too. You guys are great.

[binarybcc]

Added Claude's mcp manager as the 'source of truth' for the app

Original comment: I made this for my own use. Noob here. Apologies for barging in.
https://github.com/binarybcc/ctdiscovery
end original comment

🚀 Implementation Available: Claude Tools CLI

I've implemented a functional equivalent of the requested CLI commands in a fork of an existing tool discovery project. This provides the core functionality requested while working within the technical constraints of not having access to Claude Code's internal systems.

✅ What's Implemented

• --tools-list with filtering and multiple output formats
• --tools-inspect TOOL for detailed tool examination
• --mcp-servers and --mcp-inspect SERVER for MCP server management
• Professional table formatting and versioned JSON output
• Comprehensive testing (22 tests, 100% pass rate)

🔗 Try It

git clone -b feature/claude-tools-cli-simple https://github.com/binarybcc/ctdiscovery.git
cd ctdiscovery
npm install
node src/cli.js --tools-list --format table

📚 Documentation

- Overview: https://github.com/binarybcc/ctdiscovery/blob/feature/claude-tools-cli-simple/CLAUDE-TOOLS-CLI-README.md
- Requirements Analysis:
https://github.com/binarybcc/ctdiscovery/blob/feature/claude-tools-cli-simple/docs/RELEASE-NOTES-CLAUDE-TOOLS-CLI.md
- Technical Limitations:
https://github.com/binarybcc/ctdiscovery/blob/feature/claude-tools-cli-simple/docs/CLAUDE-TOOLS-CLI-LIMITATIONS.md

⚠️ Important Notes

This implementation provides functional equivalence using external tool detection rather than Claude Code's internal systems.
It cannot access Claude Code's internal MCP manager or live permission states, but offers comprehensive environment scanning with the same CLI interface.

Feedback welcome! This addresses the core use cases while documenting exactly what technical barriers prevent full internal system integration.

[github-actions]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.