MCP Servers

Claude Code speaks the Model Context Protocol natively. Connect a database, an API, a file server, or any MCP-compatible tool, and it becomes a first-class tool Claude can call. This lesson covers connecting servers, managing scopes, and using them in both interactive and CI modes.

What you'll learn

• claude mcp add <name> -- <command> connects a stdio MCP server; HTTP and SSE transports are also supported
• Three scopes: user (all projects), project (team-shared), local (personal, gitignored)
• MCP servers work in both interactive and print mode, use --mcp-config and --strict-mcp-config in CI

The problem

Claude Code can read files, run commands, and search the web. But it can't query your PostgreSQL database, check your Jira tickets, or read your Google Drive documents unless you explicitly connect those systems. MCP is the standard protocol for doing that, one claude mcp add command and the external tool's capabilities appear alongside built-in tools.

Options & when to use each

Scope	Flag	Storage	When to use
user	-s user	~/.claude.json	Tools you want in every project, GitHub, personal databases
project	-s project	.claude/settings.json	Team-shared tools, the project's database, shared API
local	-s local	.claude/settings.local.json	Personal project tools, your dev database, experimental APIs

Build it

Step 1: Add a GitHub MCP server

Install the GitHub MCP server into your global user scope so Claude can interact with repositories and issues across all your projects.

claude mcp add -s user github -- npx @modelcontextprotocol/server-github

Set the GITHUB_PERSONAL_ACCESS_TOKEN env var. Claude can now reference @github:issue://123 in chat.

Step 2: Add a PostgreSQL server

Register a PostgreSQL connection at the local scope to allow Claude to query and analyze your development database.

claude mcp add -s local postgres -- npx @anthropic-ai/server-postgres --connection-string "postgresql://localhost/mydb"

Step 3: Add a Puppeteer server for web testing

Add the Puppeteer MCP server to enable automated headless browser interactions and end-to-end web testing capabilities.

claude mcp add puppeteer -- npx @anthropic-ai/server-puppeteer

Step 4: Use MCP in CI

When running in continuous integration pipelines, pass strict configuration flags to ensure Claude exclusively loads the intended MCP servers.

claude --bare -p "Query the database and report" --mcp-config mcp-servers.json --strict-mcp-config

--strict-mcp-config ignores all other MCP configs, only the one you specify loads.

Step 5: Manage servers

Use these administrative commands to view your active MCP configurations or remove servers you no longer need.

claude mcp list          # list all configured servers
claude mcp remove <name> # remove a server

What goes wrong

Mistake	How you notice it	The fix
MCP server fails to start	claude mcp list shows the server but tools don't appear	The command or npx binary isn't on PATH. Test the command directly in a terminal first
MCP tools don't appear in interactive mode	Claude doesn't mention the server's tools	/reload-plugins or restart the session. MCP servers are discovered at startup
MCP output floods context	Claude's responses slow down, context usage spikes	Set export MAX_MCP_OUTPUT_TOKENS=50000 to cap MCP output. Use maxResultSizeChars annotation for large outputs
CI mode ignores MCP config	--bare mode doesn't see your MCP servers	Bare mode skips all config discovery. Use --mcp-config <file> and --strict-mcp-config explicitly

Confirm it worked

Execute these validation steps to confirm your MCP integration correctly registers a mock server and exposes its tools to Claude.

# 1. Add a simple MCP server
claude mcp add -s local test-server -- echo '{"jsonrpc":"2.0","result":{}}'

# 2. Verify it's listed
claude mcp list

# 3. Clean up
claude mcp remove test-server

Next: Plugins , packaging and distributing your extensions.