Claude Code is Anthropic's coding agent that runs in the terminal. It reads your repository, edits files, runs commands and tests, and keeps going until the task is done. On its own, though, it only sees what is on your machine. To check Sentry, open a Linear issue or read what a client asked for on WhatsApp, it needs MCP servers.
This guide shows how to add, organize and debug MCP servers in Claude Code, using the commands from the official documentation.
In one sentence: what MCP does in Claude Code
MCP (Model Context Protocol) is the standard that connects Claude Code to external tools. Each MCP server exposes a set of tools, and Claude decides when to use each one during the conversation. If you are new to the protocol, what is MCP explains it from scratch.
Adding a remote server (HTTP)
Servers that run in the cloud are added by URL:
claude mcp add --transport http notion https://mcp.notion.com/mcp
If the service expects a fixed token, it goes in a header:
claude mcp add --transport http my-api https://api.example.com/mcp \
--header "Authorization: Bearer YOUR_TOKEN"
Many remote servers use OAuth. In that case, after adding the server, run /mcp inside a session to sign in through the browser.
Adding a local server (stdio)
Local servers run as a process on your computer. The format is:
claude mcp add [options] <name> -- <command> [args...]
The -- separates Claude Code's options from the command that starts the server. Everything after it is passed through unchanged. Environment variables go with --env (or -e):
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server
A real example with WhatsApp. WACrew publishes the wacrew-mcp server on npm, which connects Claude Code to your WhatsApp panel:
claude mcp add wacrew \
-e WAC_CLOUD_URL=https://your-panel.example.com \
-e WAC_CLOUD_USER=admin -e WAC_CLOUD_PASS=your-password \
-- npx -y wacrew-mcp
After that, requests like "summarize what clients sent today" or "transcribe the voice note in group X" just work. The full walkthrough is in how to build a WhatsApp AI agent with MCP.
The three scopes: local, project and user
Where the configuration is stored decides who sees the server. You pick it with --scope (or -s):
| Scope | Applies to | Shared with the team | Stored in |
|---|---|---|---|
local (default) | The current project only | No | ~/.claude.json |
project | The current project only | Yes, through Git | .mcp.json at the project root |
user | All your projects | No | ~/.claude.json |
Rules of thumb:
- Personal credentials live in
localoruser, never inproject. - Tools the whole team uses in that repository go in
project. The.mcp.jsonfile is committed. - Tools you use everywhere, like a search server, go in
user.
The .mcp.json file
In the project scope, the configuration is a JSON file at the repository root:
{
"mcpServers": {
"wacrew": {
"command": "npx",
"args": ["-y", "wacrew-mcp"],
"env": {
"WAC_CLOUD_URL": "${WAC_CLOUD_URL}",
"WAC_CLOUD_USER": "${WAC_CLOUD_USER}",
"WAC_CLOUD_PASS": "${WAC_CLOUD_PASS}"
}
}
}
}
${VAR} is expanded from your environment, so the password does not have to live in the repository. For safety, Claude Code asks for approval before enabling servers that come from a .mcp.json. A cloned repository cannot approve itself.
Managing servers
claude mcp list # list servers and their status
claude mcp get wacrew # details for one server
claude mcp remove wacrew # remove it
Inside a session, /mcp shows the status of each connection, handles sign-in for OAuth servers and turns servers on or off for the project without deleting the configuration.
claude mcp list shows a status next to each server, such as "Connected", "Needs authentication" or "Failed to connect". A failure there means Claude Code could not reach that server, not that the command itself errored.
Common problems and fixes
The server shows "Pending approval". It comes from a .mcp.json you have not approved yet. Run claude in the project and accept it in the trust prompt.
The server is slow to start. MCP_TIMEOUT sets the startup timeout. For example, MCP_TIMEOUT=10000 claude gives it ten seconds.
A tool returns too much text. Claude Code warns when a tool's output goes past 10,000 tokens and caps it at 25,000 by default. MAX_MCP_OUTPUT_TOKENS changes that limit. Even better is a tool that accepts filters, like "last 50 messages", instead of returning everything.
The environment variable does not arrive. Remember the --. Claude Code's options go before it and the server command goes after. Put at least one option between --env and the server name, or the name is read as one more variable.
A server written for Claude Desktop or Cursor. Instructions for other clients usually include a JSON block with command and args. You can use the same command with claude mcp add, or paste the block with claude mcp add-json.
Good practices
- Few servers per project. Each server adds tools the model has to consider. Too many tools muddy the choice.
- Least privilege. Give the server the least powerful key that solves the problem.
- Anything that leaves your machine needs confirmation. Sending messages, publishing and payments should go through your approval. For WhatsApp, WACrew keeps every conversation in confirm mode by default.
- Test before sharing. Validate in
localand only then move it toproject.
Summary
Claude Code gets external tools through MCP servers. Remote ones are added with claude mcp add --transport http, local ones with claude mcp add <name> -- <command>. The scope decides whether the configuration is yours alone or the whole team's, and /mcp handles sign-in and diagnostics. To pick a WhatsApp server for it, see the WhatsApp MCP servers comparison.



