Claude Code CLI MCP Guide: Connect Claude Code to External Data and Services
Learning Objectives
By the end of this tutorial, you will be able to:
- Understand how MCP (Model Context Protocol) works with Claude Code
- Add MCP servers to Claude Code CLI using the
claude mcp addcommand - Check the connection status of your MCP servers
- Use MCP tools in Claude Code conversations
- Manage server scope (local, user, project)
Time needed: 15–20 minutes
Difficulty: Beginner
Which version is covered? This tutorial covers Claude Code CLI — the command-line version of Claude Code. MCP servers are configured through the claude mcp command and .mcp.json or ~/.claude.json configuration files. If you want the desktop app instead, see the Claude Code Desktop MCP Guide.
Prerequisites
Before you begin, make sure you have:
| Requirement | Details |
|---|---|
| Claude Code CLI installed | claude --version should print a version number. Not installed? Follow the Claude Code CLI Beginner's Guide first. |
| Claude Code authenticated | Run claude once and sign in with your Anthropic/Claude account |
| A terminal open | All commands in this tutorial run from the terminal |
What is MCP?
MCP (Model Context Protocol) is an open standard that lets AI assistants like Claude Code connect to external tools and data sources. Instead of every tool building its own custom integration, they all speak the same protocol.
An MCP server is a small program that exposes tools, data, or services to the AI assistant. For example:
- A GitHub MCP server lets Claude Code read issues, create pull requests, and browse repositories
- A database MCP server lets Claude Code query your database with natural language
- An issue tracker MCP server lets Claude Code access JIRA, Linear, or Notion directly
Claude Code supports two types of MCP servers:
- HTTP servers (recommended): hosted at a URL, no local process needed
- Stdio servers: run as a local program on your machine
How Claude Code MCP Works
Claude Code CLI has built-in MCP support. You add servers with the claude mcp add command, which writes the server configuration to a file. There are three scopes:
- Local (default): private to you, active only in the current project directory
- User: private to you, active in all your projects
- Project: shared with teammates via
.mcp.jsoncommitted to the repository
Once a server is added, its tools are available to Claude Code in every session. Claude automatically chooses the right tool based on your prompt.
Step 1: Check Your MCP Setup
First, confirm your Claude Code version supports MCP:
claude --versionWhat you should see: A version number (v2.1.x or later). MCP support is built into all recent Claude Code versions.
Now check what servers you already have:
claude mcp listWhat you should see: A list of configured MCP servers, or a message like "No MCP servers configured."
Step 2: Find an MCP Server
Claude Code MCP servers are available from several sources:
- MCP directory on Cataito: browse /mcp — 55+ curated MCP servers ready to connect
- Anthropic Directory: claude.ai/directory — reviewed connectors from Anthropic
- GitHub: search for
mcp-server— thousands of community servers exist - npm: many servers install with
npx
For this tutorial, we will connect the **GitHub MCP server** — one of the most popular servers, which lets Claude Code read repositories, issues, and pull requests.
Step 3: Add an HTTP MCP Server
HTTP servers are the recommended way to connect to remote MCP servers. They are hosted at a URL and require no local setup.
Open a terminal and register the GitHub MCP server:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/What you should see: A confirmation message like Added HTTP MCP server github with URL: ... followed by a File modified: line showing the configuration file.
Add a Stdio Server (Alternative)
If the server runs as a local command, use the stdio transport:
claude mcp add my-db-server -- npx -y @modelcontextprotocol/server-postgresWhat you should see: The command completes without error, and Claude Code writes the server entry to the configuration file.
Step 4: Check the Connection Status
Verify the server is connected:
claude mcp listWhat you should see: The server appears with a status indicator:
| Status | Meaning |
|---|---|
✔ Connected | Ready to use |
! Needs authentication | Server needs a browser sign-in or token |
✘ Failed to connect | Server didn't respond |
You can also inspect a specific server:
claude mcp get githubWhat you should see: The server details, including transport type, URL, and status.
Step 5: Use MCP Tools in a Conversation
Now start a Claude Code session and use the MCP tools:
claudeThen type a prompt that uses the connected service, for example:
List the open issues in the facebook/react repositoryWhat you should see: Claude Code calls the GitHub MCP server's tools automatically. The first time Claude uses a tool, it asks for your permission. Approve it to continue. The tool call in Claude's output is labeled with the server name, so you can confirm the answer came from the MCP server.
You can also type /mcp inside a session to see which MCP tools are available.
Step 6: Change Server Scope (Optional)
By default, servers are added at local scope (private to you, in the current project). To register a server for all your projects:
claude mcp add --scope user github -- npx -y @modelcontextprotocol/server-githubTo share a server with teammates via .mcp.json:
claude mcp add --scope project github -- npx -y @modelcontextprotocol/server-githubStep 7: Remove a Server (Optional)
If you no longer need a server, remove it:
claude mcp remove githubWhat you should see: The server disappears from claude mcp list.
Troubleshooting
| Problem | Cause | Fix | |
|---|---|---|---|
claude: command not found | Claude Code CLI not installed | Install it: `curl -fsSL https://claude.ai/install.sh | bash`, then restart your terminal |
claude mcp not recognized | Outdated Claude Code | Update: claude update | |
! Needs authentication | Server requires OAuth or token | Check the server's README for auth requirements. Use --header to pass a token, or run claude to trigger a browser sign-in | |
✘ Failed to connect | Server URL is wrong or unreachable | Verify the URL and your internet connection. Try curl <url> to test | |
npx: command not found | Node.js not installed | Install Node.js LTS from nodejs.org, then restart your terminal | |
| Server connected but tools fail | Server needs an API key or environment variable | Check the server's documentation for required env vars, set them, then restart Claude Code |
FAQ
Do I need a paid plan to use MCP with Claude Code? Yes. MCP support requires a paid Claude plan (Pro, Max, or higher).
Can I use the same MCP servers in both CLI and Desktop? Yes — you can import Desktop servers into CLI with claude mcp add-from-claude-desktop. They share the same configuration format.
What is the difference between local, user, and project scope? Local scope saves the server to the project's .mcp.json; user scope saves to ~/.claude.json; project scope saves to .mcp.json (shared with teammates).
How do I see which MCP servers are available in a session? Type /mcp inside a Claude Code session.
Can I expose Claude Code as an MCP server to other tools? Yes — run claude mcp serve to expose Claude Code's tools to other MCP clients. This is an advanced use case.
Next Steps
- Browse the MCP directory on Cataito — 55+ curated MCP servers ready to connect
- Learn more Claude Code CLI commands in the Claude Code CLI Beginner's Guide
- Use the Claude Code Desktop MCP Guide if you prefer a graphical interface
