MCP: Model Context Protocol - FAQ

The Model Context Protocol (MCP) connects Claude Code to external tools (GitHub, browsers, databases) via an open standard. This FAQ covers MCP server configuration, security, and concrete use cases for automating your development workflows.

MCP (Model Context Protocol) is an open protocol created by Anthropic that standardizes communication between AI models and external tools. MCP allows Claude Code to interact with hundreds of community servers covering services like GitHub, Brave Search, or Playwright. MCP was rapidly adopted across the developer community.

This protocol operates on a client-server model where Claude Code acts as the MCP client and connects to one or more servers exposing tools.

To understand the protocol fundamentals, check the dedicated Model Context Protocol page which details the complete architecture.

Key takeaway: MCP is an open standard that separates the AI model from the tools it uses, making the ecosystem extensible.

How does the Model Context Protocol (MCP) work?

MCP operates on a client-server model with three layers: transport, protocol, and tools. Claude Code, as an MCP client, discovers available tools at session startup, then invokes them on demand.

The transport defines how messages flow. The stdio protocol launches a local process and communicates via stdin/stdout. The SSE (Server-Sent Events) transport uses HTTP for remote servers. Since the MCP 2025-03-26 specification, the HTTP streamable transport is gradually replacing SSE.

Each server exposes a list of tools with their JSON schema. Claude Code receives this list and decides when to call a tool based on your conversation context. Tool discovery is typically fastest with the local stdio transport, while remote transports add network latency.

To configure your initial environment, follow the installation and first launch guide before adding MCP servers.

Key takeaway: MCP separates transport, protocol, and tools. Claude Code automatically discovers tools exposed by each connected server.

How to add an MCP server to Claude Code?

Run the claude mcp add command followed by the server name and launch command. Claude Code saves the configuration in your .mcp.json file.

Here is how to add a stdio server in one command:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

For a remote server, specify the transport with the --transport flag. HTTP streamable is the recommended remote transport (specification 2025-03-26):

claude mcp add --transport http my-api https://api.example.com/mcp/stream

The SSE transport is deprecated. Use HTTP streamable instead where available; only fall back to SSE for servers that have not yet migrated:

claude mcp add --transport sse my-remote-server https://api.example.com/mcp

In practice, the claude mcp add command accepts three transports: stdio (default for local servers), http (recommended for remote servers), and sse (deprecated, use http instead where available). Each added server persists between sessions thanks to the configuration file.

Check the MCP cheatsheet to find all commands at a glance.

Key takeaway: claude mcp add -- is enough to connect a local server; add --transport http for remote servers (the deprecated --transport sse remains only as a fallback).

How to list and manage configured MCP servers?

Use claude mcp list to display all MCP servers registered in your configuration. This command shows the name, transport, and status of each server.

claude mcp list

To remove an unnecessary server, run:

claude mcp remove github

To get the details of a specific server:

claude mcp get github

In practice, project-scope servers are stored in .mcp.json at the root of your project, while user-scope (and local-scope) servers are stored in ~/.claude.json in your home directory. You can edit these files manually if you prefer.

The essential slash commands cover other useful commands for managing your daily Claude Code sessions.

Key takeaway: claude mcp list and claude mcp remove give you complete control over your configured servers.

How to use MCP tools during a Claude Code session?

MCP tools are automatically available as soon as the server is configured. Claude Code invokes them based on your conversation context, without any special syntax on your part.

For example, with the GitHub server configured, simply ask:

Create an issue on the repo my-org/my-project with the title "Bug: crash at startup"

Claude Code identifies the create_issue tool from the GitHub server and calls it with the appropriate parameters. The permissions and security system asks for your confirmation before any sensitive action.

Here is how to check the available tools in session. Type /mcp in your Claude Code session to display the list of connected servers and their tools. In practice, a GitHub server exposes many tools for issues, pull requests, code search, and more (create_issue, search_repositories, create_pull_request, etc.).

To dive deeper into using tools in conversation, explore the FAQ on your first conversations with Claude Code.

Key takeaway: you do not need special syntax: describe your intent in natural language and Claude Code selects the appropriate MCP tool.

What are the most popular MCP servers?

The three most popular MCP servers are GitHub, Brave Search, and Playwright. hundreds of community servers are available as open source.

GitHub exposes many tools for issue management, pull requests, code search, and file reading. The official recommendation is now the remote GitHub MCP server over HTTP (the older @modelcontextprotocol/server-github npm package is deprecated in favor of github/github-mcp-server). It requires a GitHub personal access token.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

Brave Search (@modelcontextprotocol/server-brave-search, now deprecated and no longer maintained) enables real-time web searches. It requires a Brave API key.

claude mcp add brave -- npx -y @modelcontextprotocol/server-brave-search
export BRAVE_API_KEY=your_key

Playwright (@playwright/mcp) automates the browser: screenshots, navigation, DOM interaction.

claude mcp add playwright -- npx -y @playwright/mcp@latest

In practice, GitHub is one of the most commonly configured first servers. SFEIR Institute recommends adding GitHub and Brave Search as the minimal foundation for a productive workflow.

The MCP checklist guides you step by step through installing these essential servers.

Key takeaway: GitHub, Brave Search, and Playwright cover the most common use cases. Start with these three servers.

How to configure environment variables for an MCP server?

Pass environment variables with the --env flag when adding the server. These variables are written in plain text to your local JSON configuration (~/.claude.json or .mcp.json), so handle secrets with care. For sensitive values, prefer environment-variable expansion such as ${VAR} rather than hardcoding the secret.

claude mcp add --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_abc123 github -- npx -y @modelcontextprotocol/server-github

For a server requiring multiple variables:

claude mcp add \
 --env DATABASE_URL=postgresql://localhost:5432/mydb \
 --env DATABASE_TOKEN=secret123 \
 database -- npx -y @example/server-postgres

In practice, you can also define variables in your shell (export VAR=value) before launching Claude Code. The MCP server then inherits the parent process environment.

The manual configuration in .mcp.json looks like this:

{
 "mcpServers": {
 "github": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-github"],
 "env": {
 "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_abc123"
 }
 }
 }
}

For advanced configuration file management, check the FAQ on the CLAUDE.md memory system which explains the settings file hierarchy.

Key takeaway: use --env to inject API tokens at the time of addition, or configure them in .mcp.json for finer control.

How to secure your MCP servers?

Apply the principle of least privilege: only give each server the permissions strictly necessary. Claude Code asks for your authorization before each unapproved MCP tool call.

Three essential security rules:

1. Limit API token scopes (e.g., GitHub token in read-only if you do not need write access)
2. Verify the source of MCP servers before installation - prefer official @modelcontextprotocol/ packages
3. Audit exposed tools with claude mcp list before approving permissions

In practice, overly broad token scopes are one of the most common sources of risk. Create a dedicated GitHub token with only the repo:read and issues:write scopes if your workflow allows it.

The Claude Code permissions system adds a layer of protection. Each MCP tool is classified by risk level. Read tools (search, get) are approved once, while write tools (create, delete) require confirmation on each call.

To understand the permissions model in detail, read the FAQ on Claude Code permissions and security.

Key takeaway: least privilege on tokens, source verification for servers, and audit of exposed tools. These three practices cover the essentials of MCP security.

What common problems arise with MCP and how to solve them?

The most frequent problem is server connection failure, often caused by a missing binary or absent environment variable. Verify first that the server command works manually.

Quick diagnosis:

# Check that npx finds the package
npx -y @modelcontextprotocol/server-github --help

# Check environment variables
echo $GITHUB_PERSONAL_ACCESS_TOKEN

# Relaunch MCP discovery in session
/mcp

The MCP troubleshooting guide covers 25+ error scenarios with their detailed solutions.

Key takeaway: most MCP errors are resolved by checking three things: the server binary, environment variables, and network connectivity.

Can you create your own MCP server?

Yes, you can create an MCP server in fewer than 50 lines of code with the official TypeScript or Python SDK. The SDK handles the transport and protocol - you only implement the business logic.

Here is a minimal MCP server in TypeScript (Node.js 20+):

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.tool("hello", { name: z.string() }, async ({ name }) => ({
 content: [{ type: "text", text: `Hello ${name}!` }]
}));

const transport = new StdioServerTransport();
await server.connect(transport);

Save this file then add it to Claude Code:

claude mcp add my-server -- node my-server.js

the official MCP TypeScript and Python SDKs support stdio, SSE, and HTTP streamable transports.

To explore the agentic coding paradigm and understand how agents use these tools, this complementary FAQ provides useful insight.

Key takeaway: the MCP SDK handles transport and protocol - your custom server only contains business logic, making creation accessible in under an hour.

How does MCP integrate into a developer's daily workflow?

MCP transforms Claude Code into a central hub that orchestrates your development tools. Instead of switching between terminal, browser, and IDE, you describe your intent and Claude Code coordinates the MCP calls.

A typical workflow with MCP:

1. Search for a reported bug: Claude Code uses search_issues (GitHub MCP)
2. Analyze the context: Claude Code reads the relevant files via get_file_contents
3. Verify a hypothesis: Claude Code launches brave_search to find documentation
4. Fix the code: Claude Code directly edits the files
5. Validate visually: Claude Code captures a screenshot via browser_take_screenshot
6. Create the pull request: Claude Code calls create_pull_request

In practice, this workflow can meaningfully cut bug resolution time. The main gain comes from eliminating context switches between tools.

If you want to master these advanced workflows, the one-day Claude Code training from SFEIR Institute lets you practice MCP configuration and tool orchestration through hands-on labs. To go further, the two-day AI-Augmented Developer training covers complete integration into your CI/CD pipeline.

Key takeaway: MCP eliminates context switching between tools - you stay in Claude Code while the protocol orchestrates GitHub, the browser, and your APIs.

Should you use MCP in project mode or global mode?

Configure MCP at the project level (.mcp.json at the root) for repository-specific servers, and at the user level (~/.claude.json in your home directory) for cross-cutting tools. This separation avoids conflicts between projects.

Servers to configure globally:

• Brave Search (web search, useful everywhere)
• Playwright (visual testing, cross-cutting)

Servers to configure per project:

• GitHub (specific token and repo)
• Database (local connection)
• Custom MCP servers (business tools)

// .mcp.json (project-scope config)
{
 "mcpServers": {
 "brave": {
 "command": "npx",
 "args": ["-y", "@modelcontextprotocol/server-brave-search"],
 "env": { "BRAVE_API_KEY": "your_key" }
 }
 }
}

For user-scope (global) servers, add them with claude mcp add --scope user, which writes the entry to ~/.claude.json (not settings.json). MCP servers are never configured in settings.json.

In practice, the project configuration takes precedence over the user configuration when a server has the same name. This override mechanism allows you to adapt parameters per environment.

The one-day AI-Augmented Developer - Advanced training from SFEIR dives deeper into multi-project configuration strategies and team MCP architecture patterns.

Key takeaway: user scope (~/.claude.json) for cross-cutting tools, project scope (.mcp.json) for specific tools - project configuration overrides user scope in case of conflict.

How many MCP servers can be connected simultaneously?

Claude Code does not impose a fixed limit on the number of simultaneous MCP servers. Its MCP Tool Search (enabled by default) defers tool definitions until they are needed, so adding many servers has minimal impact on context and performance. To keep things tidy, disable servers you no longer use.

Each stdio server still consumes a separate system process. In practice, 10 stdio servers represent 10 Node.js or Python processes running in parallel. Monitor your memory consumption with htop if you run many local servers.

SSE and HTTP servers do not consume a local process - only the network connection is maintained. Prefer these transports for servers you use occasionally.

Key takeaway: aim for 5 to 10 active servers for an optimal balance between features and performance - disable unused servers with claude mcp remove.

What are the differences between MCP and classic API calls?

MCP standardizes tool discovery and invocation, where classic APIs require manual integration for each service. The MCP protocol adds an abstraction layer that allows the model to choose the appropriate tool based on context.

the protocol supports three primitives: Tools (actions), Resources (data), and Prompts (templates). REST APIs only cover the equivalent of Tools.

MCP does not replace APIs - it encapsulates them. A GitHub MCP server calls the GitHub REST API internally, but exposes its features in a format that Claude Code natively understands.

Key takeaway: MCP is an abstraction layer on top of APIs - it does not replace them but makes them accessible to the AI model via a standardized protocol.

---