claude mcp list: Manage MCP Servers in Claude Code

Updated 30 October 2026 · Sources & corrections

In this guide

1. What Is the Model Context Protocol?
2. Listing Servers with claude mcp list
3. Adding and Removing Servers
4. Practical Example: Adding a Filesystem Server
5. Database examples: check maintenance before copying commands
6. Understanding Scopes: local, project, and user
7. Troubleshooting MCP stdio servers that fail to start
8. Verifying Tools Are Exposed to the Agent
9. How MCP Fits the Rest of Claude Code
10. Bottom line
11. Sources and verification scope
12. 30 October 2026 correction and verification scope

If you use Claude Code for day-to-day development, the claude mcp list command lists configured servers and their reported connection status. It is one of the most useful AI developer tools commands to learn early, because MCP servers are how Claude Code talks to your files, databases, and APIs.

This guide walks through listing, adding, and removing MCP servers from the command line. You will inspect one registration, review a filesystem example, distinguish configuration scope from server permissions, and diagnose connection failures.

Everything here assumes you already have Claude Code installed. If not, install Claude CLI first, then come back.

What Is the Model Context Protocol?

The Model Context Protocol (MCP) is an open standard that lets AI agents connect to external tools and data sources through a consistent interface. Instead of pasting data into the chat, you run a small server process that exposes tools — like reading files or querying a database — and the agent calls those tools when it needs them.

Claude Code acts as an MCP client. Each server you register becomes a set of tools the agent can invoke, whether that is browsing your project directory or running a SQL query against a local database.

Listing Servers with claude mcp list

To see every MCP server currently registered, run:

claude mcp list

The output shows each server’s name, the command or URL it runs, and whether Claude Code can connect to it. A healthy server reports as connected; a broken one shows a failure status, which is your cue to troubleshoot.

Two related commands are worth knowing. claude mcp get <name> shows the full configuration of one server, and inside an interactive Claude Code session you can type /mcp to inspect servers and their tools without leaving the chat.

claude mcp get filesystem

Adding and Removing Servers

The add command syntax

The general form of the add command looks like this:

claude mcp add --transport stdio <name> -- <command> [args...]

The <name> is a short label you choose, and everything after it is the command Claude Code runs to start the server. If the server command itself takes flags that could clash with Claude’s own flags, separate them with --:

claude mcp add myserver -- npx -y @modelcontextprotocol/server-everything

The official Claude Code MCP documentation supports environment options before the separator. This is a syntax template, not a runnable server. Replace its script path; the variable is deliberately non-secret. Keep server flags after --.

claude mcp add --env EXAMPLE_SETTING=demo --transport stdio example -- node /absolute/path/to/reviewed-server.js

Removing a server

Removing a server is a single command. It deletes the configuration entry from whatever scope the server was registered in.

claude mcp remove filesystem

If a server with that name exists in more than one scope, pass the scope flag to target the right one, for example claude mcp remove filesystem -s project.

Practical Example: Adding a Filesystem Server

The filesystem server is the classic starter MCP integration. It gives Claude Code controlled read and write access to specific directories beyond the current working folder, which is handy when a project spans multiple repos.

Register it with npx, passing the directories you want to expose as arguments:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /home/user/projects /home/user/docs

The following Windows-style path is illustrative. Check your installed Claude version, executable resolution and package documentation; this article does not claim the command was run on Windows:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem "C:\Users\you\projects"

Run claude mcp list afterward, then inspect /mcp and perform a harmless test. The filesystem server documentation describes read and write tools and allowed-directory controls. Grant a disposable test directory, not your whole home folder.

Database examples: check maintenance before copying commands

The official reference-server repository lists its PostgreSQL and SQLite implementations as archived. Our earlier unverified SQLite package command and archived PostgreSQL quickstart have been removed. A package appearing in an old tutorial does not establish current maintenance or production suitability.

Choose a maintained implementation, inspect its own installation and permission documentation, and start against disposable data with a genuinely read-only database account. A server’s claimed read-only mode does not replace database permissions. Do not paste a real database password into a command copied to shell history or a shared configuration.

Understanding Scopes: local, project, and user

Every server you add is stored in one of three scopes, controlled by the -s or --scope flag. The scope decides who can see the server and where the configuration lives.

Scope	Flag	Visibility	Best for
local	-s local	Your configuration, this project	Project-specific experiments
project	-s project	Whole team via .mcp.json in the repo	Reviewed team configuration
user	-s user	You, across all projects	Personal utilities used everywhere

The default is local, which limits configuration scope to you in this project. This is not an encryption or read-only guarantee. Use project only for servers the whole team should share, since .mcp.json can be committed to version control. Never commit secrets. Inspect the actual command, endpoint and requested access before approving a shared server.

claude mcp add team-db -s project -- npx -y some-db-server --host db.internal

Troubleshooting MCP stdio servers that fail to start

A failed connection status does not identify the broken layer. First distinguish a process that never launched, a process that exited, and a running process that did not finish initialization. A local stdio server can remain silent while waiting for a client; silence alone is not evidence of a hang.

Record the server name, transport, executable, arguments, working directory and exit status if available. Inspect the details with claude mcp get <name> and the interactive /mcp panel. The Claude Code MCP reference documents these controls. Check the installed version before assuming the same menu or retry behavior in every release.

Choose the next check from the evidence

Observation	Check next	Avoid assuming
Executable cannot be found	Resolve the runtime in the environment used by the client, then verify its configured path.	A terminal’s PATH is identical to the client’s.
Process exits immediately	Inspect exit status and stderr for dependency, configuration or permission errors.	Increasing a timeout will repair a crash.
Process stays open without output	Connect with a protocol-aware client and observe initialization.	A quiet stdio server is broken.
Client reports invalid JSON or framing errors	Look for banners, progress messages or debug prints on stdout.	All text from the child is a protocol message.
Initialization succeeds but tools are missing	Inspect advertised capabilities and tool discovery separately.	Successful process launch proves tools are usable.

Check paths without printing secrets

The official debugging guide explains why working directories and inherited environments differ between client launches. Prefer explicit paths where the client supports them. Check whether required secret variables are present through your client’s supported configuration mechanism; do not paste their values into a diagnostic report or dump the entire environment.

These illustrative PowerShell checks resolve Node and test one script path without launching a server. Replace the path before using them:

Get-Command node -ErrorAction Stop | Select-Object Source

Test-Path -LiteralPath 'C:\path\to\server\index.js'

A successful result proves only that this PowerShell process can resolve that command and see that path. Repeat the comparison against the actual client’s launch configuration. For a Claude installation problem rather than an MCP child-process failure, start with our Claude CLI installation guide.

Keep stdout for the protocol

The stdio transport specification reserves stdout for MCP JSON-RPC messages and permits diagnostic logs on stderr. Do not merge stderr into stdout in a launcher. A line such as “starting server” on stdout can corrupt the protocol stream even if the server is otherwise healthy. Conversely, stderr may contain ordinary diagnostics; its presence alone does not establish failure.

Test initialization with Inspector

The official MCP Inspector can launch a local stdio server and expose its connection and protocol behavior. After reviewing the package and server you intend to run, and checking the current Node requirements, the documented launch pattern is:

npx @modelcontextprotocol/inspector node C:/path/to/server/index.js

Use your server’s real executable and arguments. This command may fetch the Inspector package and runs the selected server; it is not merely a configuration linter. Keep its token-bearing local URL and raw logs private. Inspect initialization first, then tool discovery. A manual server process that waits for stdin has not completed either check by itself.

If Inspector connects but Claude Code does not, compare executable paths, arguments, environment and working directory rather than deleting the configuration immediately. Back up the entry before editing it. In an interactive Claude Code session, the current reference documents Reconnect in /mcp for a stdio server that failed or exited. Change one item and retry so the result remains interpretable.

This sequence targets local stdio. Remote HTTP authentication, endpoint and proxy failures require a different investigation. MCP server access also differs from reusable task instructions; see our Claude Code skills guide for that distinction.

Verifying Tools Are Exposed to the Agent

A connected server is only half the story — you also want to confirm the agent can actually call its tools. Start a Claude Code session and type /mcp to see each server, its status, and the tools it exposes.

Then give the agent a task that requires the tool. Ask it to list files in the directory you exposed to the filesystem server, or to describe a table in your database, and watch whether it invokes the MCP tool rather than improvising.

MCP tools appear with a prefix like mcp__filesystem__read_file or mcp__postgres__query. The first time the agent uses one, Claude Code asks for permission, and you can approve it once or always for that tool.

If a tool never appears, inspect approval, connection and tool discovery separately. Missing tools alone do not prove the server connected.

How MCP Fits the Rest of Claude Code

MCP servers are one of three main ways to extend Claude Code, alongside hooks and Claude Code skills. Skills package reusable instructions and workflows, while MCP servers give the agent live access to external systems.

In practice they complement each other: a skill might define how your team writes migrations, while an MCP database server lets the agent inspect the actual schema before writing one. Managing those servers with the claude mcp list command keeps the whole setup visible and predictable.

Bottom line

The claude mcp list command is your dashboard for MCP integrations: it shows every registered server and whether it is actually connecting. Pair it with claude mcp add and claude mcp remove, and you can manage the entire lifecycle from the terminal.

Start with a disposable test directory and inspect one server at a time. Configuration scope controls where a registration applies; the server and underlying system determine its real capabilities. Match the next diagnostic check to the reported failure.

Sources and verification scope

This is a documentation-based guide. Command outputs and configuration examples are illustrative unless explicitly identified as recorded test results. Check the installed version and platform; a successful syntax check does not establish hardware compatibility.

• Claude Code MCP reference
• Claude Code CLI reference

Editorial update, 21 October 2026: source references and verification scope added; identified command, feature or wording errors corrected. Read our sourcing and correction policy.

Editorial update, 23 October 2026: replaced the stdio startup troubleshooting section to distinguish process launch, initialization, stdout framing and tool discovery. PowerShell path checks were syntax-checked locally; Inspector and a live MCP server were not run for this update. The featured image is an original generated illustration.

30 October 2026 correction and verification scope

AI Models News checked the linked Claude Code and reference-server documentation. This correction removes an unverified SQLite launch example, identifies archived database reference implementations, fixes an ambiguous environment-option example and clarifies that configuration scope is not a permission boundary. Existing stdio diagnostics are preserved. No Claude Code connection, database access or Windows runtime test is claimed. Examples require your own reviewed server and test environment. For configuration features inside Claude Code, see our skills, memory and hooks guide. Read our editorial policy.