Claude Code MCP CLI: Complete Command Reference

The Claude Code MCP CLI is the primary way to manage Model Context Protocol (MCP) servers from the command line.

Instead of manually editing configuration files, you can register, inspect, update, and remove MCP servers using a small set of CLI commands.

This guide covers every commonly used Claude MCP command, explains when to use each one, provides production-ready examples, highlights common mistakes, and links to related setup guides.

Whether you're configuring your first local MCP server or managing multiple production deployments, this reference is designed to be the page you bookmark and return to whenever you need the correct syntax.

What You'll Learn

By the end of this guide, you'll know how to:

✅ add MCP servers

✅ import JSON configurations

✅ inspect existing servers

✅ list configured servers

✅ remove servers

✅ understand configuration scopes

✅ configure environment variables

✅ troubleshoot common CLI errors

✅ follow production best practices

Claude MCP CLI Commands at a Glance

Quick Command Cheat Sheet

claude mcp add
claude mcp add-json
claude mcp list
claude mcp get
claude mcp remove

If you're new to Claude Code, start with claude mcp add, then use claude mcp list and claude mcp get to verify that your server has been configured correctly before testing tools.

These commands form the core workflow for configuring MCP servers in Claude Code. Rather than editing configuration files manually, most developers will spend nearly all of their time using these CLI commands. (Claude Code MCP Documentation)

Typical Claude MCP Workflow

A normal development workflow looks like this:

Install MCP Server

        │

        ▼

claude mcp add

        │

        ▼

claude mcp list

        │

        ▼

claude mcp get

        │

        ▼

Test Tools

        │

        ▼

Deploy

        │

        ▼

Verify

Need a complete walkthrough of configuration, scopes, authentication, environment variables, and troubleshooting?

→ Claude Code MCP Server Configuration: Complete Guide

This workflow minimizes configuration mistakes and makes it much easier to diagnose problems before deploying MCP servers into production.

If you're completely new to MCP, start here first:

→ What Is an MCP Server?

Command 1 — claude mcp add

Purpose

claude mcp add registers a new MCP server with Claude Code.

It is the command you'll use most often.

Use it whenever you want to:

• add a local stdio server
• register a remote server
• configure a new development tool
• connect Claude Code to a production MCP server

Syntax

claude mcp add <name> [options]

Local stdio Example

claude mcp add github \
  --command npx \
  --args -y @modelcontextprotocol/server-github

Claude Code launches the process automatically and communicates with it using the stdio transport.

Remote HTTP Example

claude mcp add weather \
  --transport http \
  --url https://example.com/mcp

This approach is commonly used for hosted MCP servers shared across multiple developers.

When Should You Use It?

Choose claude mcp add when:

• creating a new configuration
• registering a local development server
• connecting to an existing hosted server
• testing new integrations

Looking for a production-ready starting point?

→ Production MCP Server Templates

Browse reusable TypeScript and Python MCP server templates with Docker, authentication, health monitoring, structured logging, automated tests, and CI/CD already configured.

If you're building your own server first, see:

→ How to Connect Claude to Any API with MCP

→ OpenAPI to MCP: Complete Guide

Common Mistakes

The most common issues include:

• incorrect executable paths
• unsupported transport
• missing environment variables
• server startup failures
• invalid command arguments

Always verify that the server starts successfully outside Claude Code before registering it.

Related Commands

• claude mcp list
• claude mcp get
• claude mcp remove

Command 2 — claude mcp add-json

Purpose

claude mcp add-json registers an MCP server from a complete JSON configuration.

Unlike claude mcp add, which builds the configuration from CLI arguments, this command imports an entire MCP definition in one step.

It's particularly useful when:

• documentation provides JSON examples
• teammates share a working configuration
• importing existing project configurations
• installing hosted MCP servers

Many vendors now publish JSON snippets specifically designed for claude mcp add-json, making it the preferred installation method for more complex integrations.

Syntax

claude mcp add-json <name> '<json>'

Example

claude mcp add-json github '{
  "type":"stdio",
  "command":"npx",
  "args":[
    "-y",
    "@modelcontextprotocol/server-github"
  ]
}'

Claude Code validates the JSON before saving the configuration.

HTTP Example

Hosted MCP servers commonly look like this:

claude mcp add-json weather '{
  "type":"http",
  "url":"https://example.com/mcp"
}'

For authenticated services, additional headers or environment-variable references may also be included depending on the server implementation.

When Should You Use It?

Choose add-json when:

• documentation already provides JSON
• installing enterprise MCP servers
• copying configurations between projects
• importing shared team configurations

It also makes it easier to keep configuration examples consistent across documentation.

Common Mistakes

Typical issues include:

• invalid JSON syntax
• missing quotes
• trailing commas
• incorrect transport type
• forgetting to escape quotation marks in the shell

Before blaming Claude Code, validate that the JSON itself is valid.

Related Commands

• claude mcp add
• claude mcp list
• claude mcp get

Command 3 — claude mcp list

Purpose

claude mcp list displays every MCP server currently configured.

This is usually the first command developers run after adding a server.

Syntax

claude mcp list

Example

claude mcp list

Typical output includes:

• server name
• transport
• configuration scope
• current status

The exact formatting may change between Claude Code versions, but the command remains the quickest way to verify that a server was registered successfully.

When Should You Use It?

Run claude mcp list whenever you want to:

• verify installation
• inspect configured servers
• confirm the correct scope
• troubleshoot missing servers

It's also useful before removing or updating an existing configuration.

Common Mistakes

Developers sometimes assume a failed Tool call means the server wasn't installed.

Instead:

1. Run claude mcp list.
2. Confirm the server appears.
3. Then continue debugging authentication or startup issues.

Related Commands

• claude mcp get
• claude mcp remove

Command 4 — claude mcp get

Purpose

claude mcp get displays the configuration for one specific MCP server.

Instead of showing every configured server, it focuses on a single installation.

Syntax

claude mcp get <server-name>

Example

claude mcp get github

Depending on the configuration, you'll typically see details such as:

• transport
• command
• arguments
• URL
• scope
• environment-variable references

This makes get one of the most useful debugging commands in the CLI.

When Should You Use It?

Use get when:

• checking an imported configuration
• confirming transport settings
• debugging authentication
• verifying environment variables
• reviewing a production deployment

Related Commands

• claude mcp list
• claude mcp add
• claude mcp remove

Command 5 — claude mcp remove

Purpose

claude mcp remove removes a configured MCP server from Claude Code.

This affects only the local configuration—it does not uninstall packages or delete the remote MCP server itself.

Syntax

claude mcp remove <server-name>

Example

claude mcp remove github

After removing the server, verify the result:

claude mcp list

The removed server should no longer appear.

When Should You Use It?

Typical situations include:

• cleaning up old configurations
• replacing an outdated server
• removing temporary development servers
• troubleshooting configuration conflicts

Common Mistakes

claude mcp remove only removes the configuration.

It does not:

• uninstall npm packages
• delete Docker containers
• remove hosted MCP servers
• revoke OAuth tokens

Those tasks must be handled separately.

Understanding Installation Scopes

Claude Code supports multiple installation scopes for MCP servers.

Choosing the correct scope helps keep configurations organized while making collaboration much easier.

User Scope

Use this when the server should be available across all of your projects.

Typical examples include:

• GitHub
• Slack
• Notion
• Google Drive
• Context7

Learn more:

→ GitHub MCP: Setup, Security, Tools and Production Guide

→ Slack MCP Server: Complete Guide

Project Scope

Project scope keeps the configuration inside a specific repository.

Ideal for:

• internal APIs
• team projects
• shared development environments

Local Scope

Local scope is useful for temporary testing or experimentation without affecting shared project configuration.

For a deeper explanation of configuration scopes and project configuration, see:

→ Claude Code MCP Server Configuration: Complete Guide

Real-World Workflow

A production workflow usually looks like this:

Install Server

↓

claude mcp add

↓

claude mcp list

↓

claude mcp get

↓

Test Tools

↓

MCP Inspector

↓

Deploy

↓

Verify

Before deploying a server, it's good practice to validate Tool discovery, Resources, authentication, and error handling.

Helpful guides:

→ MCP Inspector: Complete Guide

→ Test a Local MCP Server

→ Test MCP Server Online

→ Verify Any MCP Server

Common CLI Errors

Even though the Claude Code MCP CLI is straightforward, a few mistakes appear repeatedly.

Fortunately, most can be resolved within a few minutes.

"Server Not Found"

Symptoms:

• claude mcp get fails
• server doesn't appear in claude mcp list
• Claude Code cannot discover any Tools

Possible causes:

• server was never added
• incorrect server name
• configuration removed accidentally

Solution:

claude mcp list

If the server doesn't appear, register it again using either:

claude mcp add

or

claude mcp add-json

Invalid JSON

This almost always affects claude mcp add-json.

Typical mistakes include:

• trailing commas
• missing quotes
• invalid escaping
• malformed arrays

Validate the JSON before importing it.

Server Starts, but Claude Finds No Tools

This is rarely a Claude Code problem.

Instead, verify that the MCP server correctly implements:

• initialize
• tools/list
• resources/list
• prompts/list

Running the server through MCP Inspector usually identifies the issue much faster than debugging inside Claude Code.

→ MCP Inspector: Complete Guide

Authentication Errors

Common messages include:

• Unauthorized
• Forbidden
• Invalid API Key
• OAuth failed

Verify:

• API keys
• OAuth tokens
• environment variables
• token expiration
• required headers

Authentication problems almost always originate inside the MCP server or the target API—not Claude Code itself.

Environment Variables Not Loaded

If your server depends on environment variables, verify:

• variable names
• shell configuration
• Docker environment
• CI/CD secrets
• deployment platform

Never hardcode credentials directly into configuration.

HTTP Connection Errors

Typical causes:

• incorrect URL
• HTTPS problems
• reverse proxy configuration
• firewall rules
• server offline

Before debugging Claude Code, test the endpoint independently.

→ Test MCP Server Online

Where Is claude mcp serve?

Some developers search for a claude mcp serve command, expecting Claude Code to expose itself as an MCP server.

At the time of writing, the primary Claude Code MCP workflow focuses on adding, managing, inspecting, and removing external MCP servers using commands such as:

• claude mcp add
• claude mcp add-json
• claude mcp list
• claude mcp get
• claude mcp remove

If new CLI commands are introduced in future Claude Code releases, always refer to the official documentation for the latest syntax and supported workflows.

Production Best Practices

Once your CLI configuration works correctly, the next goal is keeping it maintainable.

The following recommendations are based on common production deployments and the official MCP guidance.

Prefer CLI Over Manual Configuration

Whenever possible, use:

• claude mcp add
• claude mcp add-json
• claude mcp list
• claude mcp get
• claude mcp remove

Instead of editing configuration manually.

This reduces human error while making configurations easier to audit.

Keep Secrets Out of Configuration

Never commit:

• API keys
• OAuth tokens
• passwords
• client secrets

Instead, reference environment variables or use your organization's secret-management solution.

Test Before Production

Before using any MCP server in real workflows, verify:

• Tool discovery
• Resources
• Prompts
• authentication
• latency
• error handling

Recommended guides:

→ Test a Local MCP Server

→ Test MCP Server Online

Review Security

Every production MCP server should undergo a basic security review.

Check:

• authentication
• authorization
• Tool permissions
• exposed operations
• logging
• secret handling

If you're deploying your own server, also read:

→ How to Secure an MCP Server

Monitor Your Server

Monitor:

• uptime
• response times
• failed Tool calls
• authentication failures
• dependency health

Small issues become much easier to diagnose when monitoring is in place before production.

Claude MCP CLI Cheat Sheet

This table summarizes the commands you'll use most often when managing MCP servers in Claude Code.

Related Guides

Continue learning with these guides:

• What Is an MCP Server?
• Claude Code MCP Server Configuration: Complete Guide
• How to Connect Claude to Any API with MCP
• OpenAPI to MCP: Complete Guide
• TypeScript MCP Server Starter
• GitHub MCP: Setup, Security, Tools and Production Guide
• Slack MCP Server: Complete Guide
• MCP Inspector: Complete Guide
• Test a Local MCP Server
• Test MCP Server Online
• Running MCP in Production
• How to Secure an MCP Server
• Verify Any MCP Server
• Production MCP Server Templates

Final Thoughts

The Claude Code MCP CLI is designed to simplify how developers manage Model Context Protocol servers.

Instead of manually editing configuration files, the CLI provides a consistent workflow for registering, inspecting, testing, and removing MCP servers while keeping configuration organized across local, project, and user scopes. This approach reduces setup errors and aligns with the workflow recommended by the Claude Code documentation. (Claude Code MCP Documentation)

In practice, most developers only need five commands:

1. claude mcp add
2. claude mcp add-json
3. claude mcp list
4. claude mcp get
5. claude mcp remove

Mastering these commands is enough to manage the majority of Claude Code MCP workflows.

Official References

This guide is based on the official Claude Code documentation and the Model Context Protocol specification.

• Claude Code MCP Documentation
• Claude Code Settings
• Model Context Protocol Documentation
• Model Context Protocol Specification

Ready to Manage Your MCP Servers?

Once you've configured your servers with the Claude Code CLI, verify that they're ready for production.

Use Test MCP Server Online to validate connectivity, or generate a full MCP Security Report to review security, compatibility, governance, health, and production readiness.

If you're building your own server from scratch, explore the Production MCP Server Templates to accelerate development with production-ready examples.

Looking for real-world MCP implementations?

Browse the Verified MCP Directory to explore production MCP servers, compare security reports, and discover enterprise-ready implementations.