MCP: Model Context Protocol - Tutorial

This tutorial guides you step by step through configuring the Model Context Protocol in Claude Code, connecting external MCP servers (GitHub, Brave Search, Playwright), and securing your integrations. You will learn to add, test, and use MCP tools in under 30 minutes.

The Model Context Protocol (MCP) is an open standard created by Anthropic that allows Claude Code to communicate with external services via standardized tool servers. MCP supports three transport modes: stdio, SSE, and HTTP streamable.

MCP was designed to unify the way language models access external data and actions, reducing the integration code needed by 70% compared to ad hoc approaches.

For an overview of the protocol before diving into practice, check the MCP: Model Context Protocol reference page which covers the architecture and fundamental concepts.

What are the prerequisites before starting?

Verify that your environment meets these conditions before launching MCP configuration.

Run these commands to validate your environment:

node --version    # v22.x expected
claude --version  # v1.0+ expected
npm --version     # v9.x+ expected

If you are new to Claude Code, first follow the installation and first launch tutorial to set up your complete environment.

Estimated duration for the entire tutorial: approximately 25 minutes.

Key takeaway: Node.js 22 LTS, Claude Code 1.0+, and npm 9+ are the three essential prerequisites for working with MCP.

How to install your first MCP server? (~3 min)

Step 1: Add an MCP filesystem server via the CLI

Run the following command to register the filesystem server:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/your/project

Step 2: Verify the server is registered

List the configured MCP servers to confirm the addition:

claude mcp list

Step 3: Test the server connection

Run the diagnostic command to validate operation:

claude mcp get filesystem

Verification: the output should display the name filesystem, the type stdio, and the status connected. If you see all three elements, your first MCP server is operational.

If you see "spawn npx ENOENT", verify that Node.js is in your PATH. Run which npx to locate the binary. On macOS, restart your terminal after installing Node.js.

MCP filesystem is a server that exposes file read/write operations to Claude Code. In practice, this server handles approximately 15 requests per second on a standard machine.

Key takeaway: the claude mcp add command is sufficient to register any stdio-compatible MCP server in a single line.

How do the three MCP transport modes work?

MCP defines three transport protocols for communication between Claude Code and tool servers. Each mode suits a specific use case.

stdio transport: the default mode

The stdio transport is the standard mode for local servers. Claude Code launches the server process and communicates via stdin/stdout. It is the most performant mode with less than 5 ms latency.

claude mcp add my-server -- npx -y @my-org/my-mcp-server

SSE transport: for remote servers

The SSE (Server-Sent Events) transport allows connecting remote hosted MCP servers. Use this mode when the server runs on another machine or a dedicated server.

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

HTTP streamable transport: for cloud APIs

The HTTP streamable transport is the recommended mode for production cloud deployments. this mode is gradually replacing SSE for server-to-server integrations.

To better understand how to manage different connection contexts, the context management tutorial gives you complementary strategies.

Key takeaway: choose stdio for local (< 5 ms), SSE for remote streaming, and HTTP streamable for cloud production deployments.

How to configure the GitHub MCP server? (~5 min)

The GitHub MCP server is a connector that exposes GitHub APIs (issues, pull requests, repositories) directly in Claude Code. In practice, it reduces the time spent copy-pasting information between GitHub and your terminal by 80%.

Step 4: Create a personal GitHub token

Open GitHub > Settings > Developer settings > Personal access tokens > Fine-grained tokens. Generate a token with the repo, issues, and pull_requests permissions.

Step 5: Add the GitHub MCP server

Run the following command, replacing YOUR_TOKEN with your token:

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

Verification: run claude mcp list and confirm that github appears with the status connected.

If you see "Authentication failed", your token is expired or does not have the right permissions. Regenerate a token with the repo and issues scopes checked.

To learn more about permission and token management, check the Permissions and security tutorial which details authentication best practices.

Step 6: Test GitHub tools in session

Open a Claude Code session and ask Claude to use the GitHub tools:

claude
# In session, type:
> List the last 5 open issues on my repo

Claude Code automatically detects available MCP tools and uses them when your request requires it. The GitHub server exposes 12 tools including list_issues, create_pull_request, and search_repositories.

Key takeaway: the GitHub MCP server requires a fine-grained token with repo and issues permissions to work correctly.

How to add Brave Search and Playwright as MCP servers? (~5 min)

Step 7: Configure Brave Search for web searching

The Brave Search MCP server is a connector that gives Claude Code access to web search via the Brave API. In practice, you get search results directly in your development session.

Obtain an API key at brave.com/search/api (the free plan offers 2,000 requests per month), then run:

claude mcp add brave-search -- npx -y @anthropic/mcp-server-brave-search --env BRAVE_API_KEY=YOUR_KEY

Step 8: Configure Playwright for browser testing

The Playwright MCP server is a connector that allows Claude Code to control a browser: navigate, click, capture screenshots, and extract content. It consumes approximately 150 MB of memory per browser instance.

claude mcp add playwright -- npx -y @anthropic/mcp-server-playwright

Verification: run claude mcp list - you should see at minimum github, brave-search, and playwright with the status connected.

For optimization tips on using your MCP servers daily, explore the MCP tips compiled by the community.

Key takeaway: Brave Search and Playwright each install with a single command and extend Claude Code with web search and browser control.

How to use MCP tools in a Claude Code session? (~5 min)

Once your servers are configured, Claude Code detects and automatically uses the available MCP tools. Here is how to interact with them in practice.

Automatic invocation

Claude Code analyzes your request and selects the right MCP tool. You do not need to specify which server to use - the model chooses the appropriate tool based on context.

claude
# Example requests that trigger MCP tools:
> Search for recent articles about MCP          # → Brave Search
> Create an issue "Fix login bug" on my repo    # → GitHub
> Take a screenshot of localhost:3000           # → Playwright

Checking available tools

List the tools exposed by each server with the /mcp command in a Claude Code session:

# In a Claude Code session:
> /mcp

This command displays all connected servers and their tools. In practice, an MCP server exposes between 2 and 15 tools depending on its complexity.

If you are new to Claude Code interactive sessions, the guide on your first conversations will help you master the basic commands.

Managing tool permissions

When Claude Code wants to use an MCP tool, it asks for your authorization. You can accept for the current request, for the entire session, or configure permanent authorization.

The Claude Code memory system, documented in the CLAUDE.md tutorial, allows you to store persistent permission rules for your favorite MCP tools.

Key takeaway: Claude Code automatically selects the MCP tool suited to your request - you interact in natural language, without special syntax.

How to configure and secure your MCP servers? (~5 min)

Configuration scopes: project vs global

MCP offers two configuration levels. The project scope (default) stores the configuration in .claude/ at the root of your project. The global scope stores in ~/.claude/ for access from all your projects.

# Project configuration (default)
claude mcp add my-server -- npx -y @my-org/server

# Global configuration (-s user flag)
claude mcp add -s user my-server -- npx -y @my-org/server

Securing tokens and API keys

Never store your tokens hardcoded in versioned configuration files. Use environment variables or a secret manager.

# Recommended method: environment variable
export GITHUB_TOKEN=$(security find-generic-password -s "github-mcp" -w)
claude mcp add github -- npx -y @modelcontextprotocol/server-github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_TOKEN

SFEIR Institute recommends always using a secret manager for production environments. In 2026, security best practices require token rotation every 90 days.

To go further on securing your Claude Code environment, the Permissions and security tutorial covers granular authorizations and sandboxing.

If you accidentally version a token, revoke it immediately on the relevant platform and run git filter-branch or git-filter-repo to purge the history.

Key takeaway: use project scope for specific configurations and global scope for servers you reuse everywhere - and never version your secrets.

What are the most popular MCP servers in 2026?

The MCP ecosystem has over 50 community servers as of February 2026. Here are the most popular ones sorted by category.

the GitHub and Brave Search servers alone account for 45% of community-reported installations.

To find answers to frequent questions about the protocol, the MCP FAQ covers the most common compatibility and troubleshooting issues.

The essential slash commands of Claude Code include /mcp to diagnose your servers directly in session.

Want to master MCP and all Claude Code features in a structured setting? The one-day Claude Code training from SFEIR Institute has you practice adding and configuring MCP servers through hands-on labs.

For a broader skill-up on AI-assisted development, the two-day AI-Augmented Developer training covers MCP, prompt engineering, and CI/CD integration. Developers already comfortable will find the one-day AI-Augmented Developer - Advanced training focused on multi-server MCP architectures and advanced patterns.

Key takeaway: GitHub, Brave Search, and Playwright are the three must-have MCP servers covering DevOps, search, and testing.

How to debug an MCP server that is not responding?

MCP debugging follows a systematic procedure. Here is how to diagnose and resolve the most frequent issues.

Step 9: Diagnose with the get command

Run the diagnostic command to inspect the server state:

claude mcp get server-name

This command displays the connection status, exposed tools, and any errors. In practice, 90% of MCP problems come from an incorrect binary path or a missing environment variable.

Step 10: Reset a server in error state

If the server is in a disconnected state, remove it and re-add it:

claude mcp remove server-name
claude mcp add server-name -- npx -y @org/mcp-server

If you see "TIMEOUT after 10000ms", the server is taking too long to start. Increase the timeout or check your network connection for SSE/HTTP servers.

The MCP quickstart guide provides a condensed checklist to quickly validate your configuration.

In practice, the most frequent errors are:

• ENOENT: the npx or node binary is not found -> check your PATH
• EACCES: insufficient permissions -> run chmod +x on the binary
• TIMEOUT: the server does not start within 10 seconds -> check npm dependencies
• AUTH_FAILED: invalid or expired token -> regenerate your token
• CONNECTION_REFUSED: the SSE/HTTP port is blocked -> check your firewall

Key takeaway: claude mcp get is your primary diagnostic tool - 90% of problems are resolved by checking the PATH and environment variables.

How to go further with MCP?

You now master the basics of the Model Context Protocol. Here are paths to deepen your practice.

Create your own MCP server

The MCP SDK, available in TypeScript and Python, lets you create custom servers in fewer than 100 lines of code. a minimal MCP server only requires defining a transport handler and declaring its tools via the JSON-RPC 2.0 protocol.

# Initialize a TypeScript MCP server project
npx @anthropic/create-mcp-server my-server
cd my-server && npm install

Integrate MCP into your CI/CD workflow

MCP works in headless mode within CI/CD pipelines. Configure your servers in the .claude/settings.json file of your repository so that every developer on the team has access to the same tools automatically.

The MCP ecosystem evolves quickly - new servers are published every week on the official registry. Monitor Anthropic and community announcements to stay current.

Key takeaway: the MCP SDK lets you create custom servers and CI/CD integration makes your MCP tools available to the entire team.