claude mcp list: Manage MCP Servers in Claude Code

If you use Claude Code for day-to-day development, the claude mcp list command is the fastest way to see which external tools and data sources your agent can actually reach. 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 add a filesystem server, connect a SQLite or Postgres database, understand scopes, and fix servers that refuse to start.

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

You can also pass environment variables with the -e flag, which is essential for servers that need API keys or connection strings:

claude mcp add myserver -e API_KEY=your-key-here -- npx -y some-mcp-server

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

On Windows with Git Bash or PowerShell, the same command works with Windows-style paths:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem C:Usersyouprojects

Run claude mcp list afterward to confirm the server connects. Once it does, the agent can read and edit files in the allowed directories using the server’s tools.

Practical Example: Adding a Database Server

SQLite

For a local SQLite database, community MCP servers let the agent run queries against a .db file. A typical registration looks like this:

claude mcp add sqlite -- npx -y mcp-sqlite /home/user/data/app.db

Point the path at your actual database file. After the server connects, you can ask Claude Code questions like “show me the schema of the users table” and it will answer by querying the database directly instead of guessing.

Postgres

For Postgres, the reference server takes a connection string. Pass it as an argument, and keep credentials out of shared project scopes:

claude mcp add postgres -s local -- npx -y @modelcontextprotocol/server-postgres postgresql://user:password@localhost:5432/mydb

The reference Postgres server exposes read-only queries by default, which is a sensible safety posture for agent access. If you use a community server with write access, double-check its permissions before pointing it at production data.

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	Only you, only in this project	Private credentials, experiments
project	-s project	Whole team via .mcp.json in the repo	Shared dev databases, team tools
user	-s user	You, across all projects	Personal utilities used everywhere

The default is local, which keeps things private. Use project only for servers the whole team should share, since the .mcp.json file is meant to be committed to version control — never put secrets in it.

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

Troubleshooting Servers That Fail to Start

When claude mcp list shows a server as failed, the cause is almost always one of a handful of issues. Work through them in this order:

• Command not found: the runtime (npx, uvx, docker) is not on your PATH. Test the launch command directly in your terminal to see the real error.
• Wrong arguments: a missing database path or malformed connection string. Check the config with claude mcp get <name>.
• Missing environment variables: API keys or tokens not passed with -e. Re-add the server with the variables included.
• Slow startup: large npx packages can take time on first run. Run the command once manually so the package is cached.
• Windows quirks: npx-based servers sometimes need cmd /c wrapping on native Windows shells.

The single most effective debugging step is running the server’s launch command yourself, outside Claude Code. If it errors or hangs in your terminal, it will fail inside the agent too — fix it there first.

If the configuration itself is corrupted, remove the server and add it back cleanly. Editing JSON config by hand is rarely necessary.

claude mcp remove sqlite
claude mcp add sqlite -- npx -y mcp-sqlite /home/user/data/app.db

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, the server likely connected but failed to advertise its capabilities — check the server logs, and confirm you are running a current version of both Claude Code and the server package.

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 filesystem server, add a database when you need live data, and choose scopes deliberately — local for secrets, project for shared tools, user for personal utilities. When something breaks, run the launch command yourself first; the error almost always shows up there.