MCP Servers — Connecting External Tools

Claude Code is powerful on its own, but its real potential emerges when you connect it to the rest of your workflow. Need Claude to query your production database? Check Sentry for errors? Create a GitHub issue? File a Jira ticket? The Model Context Protocol (MCP) makes all of this possible through a single, open standard.

This lesson teaches you how MCP works, how to configure servers, and how to extend Claude Code's capabilities to reach any tool or data source your work demands.

Learning Objectives

Understand MCP architecture and how Claude Code communicates with external tools
Configure MCP servers using the CLI and JSON configuration
Choose the correct transport type (stdio, HTTP, SSE) for your use case
Connect popular integrations like GitHub, Slack, databases, and monitoring tools
Manage server scopes for personal, project-wide, and team-shared configurations
Apply security best practices when working with MCP servers

What Is MCP?

The Model Context Protocol is an open standard for connecting AI models to external tools and data sources. Think of it as USB-C for AI: one protocol, many integrations. Instead of building custom integrations for every tool, MCP provides a universal interface that any tool can implement.

Before MCP, connecting an AI assistant to your tools meant fragile, one-off integrations. MCP standardizes this into a clean architecture:

Claude Code (Client) <--MCP Protocol--> Server <--API/SDK--> External Service

An MCP server exposes three types of capabilities:

Tools: Actions Claude can invoke (e.g., "create a GitHub issue," "query the database")
Resources: Data Claude can read (e.g., files, database schemas, API documentation)
Prompts: Predefined prompt templates that appear as slash commands in Claude Code

When you ask Claude Code to "check Sentry for errors in the last 24 hours," it discovers the relevant MCP tool from a connected Sentry server, calls it with the right parameters, and processes the results — all within the normal conversation flow.

Transport Types

MCP servers communicate with Claude Code through different transport mechanisms. The transport you choose depends on where the server runs.

Transport	How It Works	Best For	Example
stdio	Claude spawns the server as a local child process	Local tools, CLI wrappers, custom scripts	npx -y @modelcontextprotocol/server-filesystem
HTTP (Streamable)	Remote server over standard HTTP	Cloud-hosted services, production deployments	https://mcp.notion.com/mcp
SSE (deprecated)	Remote server using Server-Sent Events	Legacy remote servers (prefer HTTP instead)	https://mcp.asana.com/sse

stdio is the most common transport for local tools. Claude Code launches the server process, communicates over stdin/stdout, and manages its lifecycle automatically.

HTTP is the recommended transport for remote servers. It uses standard HTTP requests and is the most widely supported option for cloud-based services.

SSE (Server-Sent Events) is a legacy transport for remote servers. It still works but has been deprecated in favor of HTTP. Use HTTP for new integrations where available.

Installing MCP Servers

Claude Code provides the claude mcp add command for configuring servers. The exact syntax depends on the transport type.

Adding a Remote HTTP Server

Run the add command with the HTTP transport

bash

claude mcp add --transport http <name> <url>

For example, to connect the Notion MCP server:

bash

claude mcp add --transport http notion https://mcp.notion.com/mcp

If the server requires authentication headers, pass them with --header:

bash

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Verify the server is connected

bash

claude mcp list

Or inside Claude Code, run /mcp to see all connected servers and their status.

Adding a Local stdio Server

Run the add command with the stdio transport

Use -- (double dash) to separate Claude's flags from the server command:

bash

claude mcp add --transport stdio <name> -- <command> [args...]

For example, adding a filesystem server:

bash

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

Pass environment variables with --env:

bash

claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=your_key \
  -- npx -y airtable-mcp-server

Confirm the server starts correctly

Run /mcp inside Claude Code. You should see the server listed with a green status indicator.

Windows Users: Use cmd /c Wrapper

On native Windows (not WSL), local MCP servers that use npx require the cmd /c wrapper. Without it, you'll get "Connection closed" errors because Windows cannot directly execute npx.

bash

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Option Ordering Matters

All flags (--transport, --env, --scope, --header) must come before the server name. The -- separates the server name from the command passed to the MCP server. For example:

bash

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080

This prevents conflicts between Claude Code's flags and the server's flags.

Managing Servers

Once configured, manage your servers with these commands:

bash

# List all configured servers
claude mcp list
 
# Get details for a specific server
claude mcp get github
 
# Remove a server
claude mcp remove github
 
# Inside Claude Code, check status and authenticate
/mcp

Configuration Scopes

MCP servers can be configured at three scope levels, controlling who sees the server and where the config is stored.

Scope	Stored In	Visible To	Use Case
local (default)	~/.claude.json (under project path)	Only you, only this project	Personal tools, experimental servers, sensitive credentials
project	.mcp.json in project root	Everyone on the team (committed to git)	Shared project tools, team-wide integrations
user	~/.claude.json (global)	Only you, across all projects	Personal utilities used in every project

Specify the scope with --scope:

bash

# Local (default) — private to you, this project only
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
 
# Project — shared with the team via .mcp.json
claude mcp add --transport http sentry --scope project https://mcp.sentry.dev/mcp
 
# User — available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Project-Scoped Configuration File

When you use --scope project, Claude Code creates or updates a .mcp.json file in the project root. This file is designed to be committed to version control:

json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://readonly:pass@db.example.com:5432/app"],
      "env": {}
    }
  }
}

The .mcp.json file supports environment variable expansion, allowing teams to share configuration without hardcoding secrets:

json

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Use ${VAR} for required variables and ${VAR:-default} for variables with fallback values.

Scope Precedence

When servers with the same name exist at multiple scopes, local takes priority over project, which takes priority over user. This means your personal configuration always overrides shared team settings.

Popular MCP Servers

The MCP ecosystem has grown rapidly. Here are some of the most useful servers for development workflows:

OAuth Authentication

Many cloud-based MCP servers require OAuth 2.0 authentication. Claude Code handles this flow for you.

Add the server

bash

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Authenticate inside Claude Code

Run /mcp, select the server, and choose "Authenticate." A browser window opens for you to complete the login flow.

Start using the server

Authentication tokens are stored securely and refreshed automatically. You can revoke access anytime via the /mcp menu.

For servers that don't support automatic OAuth discovery, you may need to pre-register an OAuth app and provide credentials manually:

bash

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

The --client-secret flag prompts for the secret with masked input so it never appears in your shell history.

Building Custom MCP Servers

When no existing server covers your needs, you can build your own. The MCP SDK is available for both TypeScript and Python.

A minimal MCP server exposes tools that Claude can discover and invoke. Here is a simplified TypeScript example showing the structure:

typescript

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
});
 
// Define a tool
server.tool(
  "get_weather",
  "Get current weather for a city",
  { city: { type: "string", description: "City name" } },
  async ({ city }) => {
    const data = await fetch(`https://api.weather.com/v1/current?q=${city}`);
    const weather = await data.json();
    return {
      content: [{ type: "text", text: JSON.stringify(weather, null, 2) }],
    };
  }
);
 
// Connect via stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

After building the server, register it with Claude Code:

bash

claude mcp add --transport stdio weather -- node /path/to/weather-server.js

The MCP SDK also supports exposing resources (data Claude can read on demand) and prompts (reusable prompt templates). See the full SDK documentation at modelcontextprotocol.io/quickstart/server for details.

MCP Tool Search

When you have many MCP servers configured, loading every tool into context wastes tokens. Claude Code solves this with Tool Search -- a system that dynamically loads tools on demand.

Tool Search activates automatically when your MCP tool definitions exceed 10% of the context window. Instead of preloading all tools, Claude searches for the relevant ones when needed.

You can control this behavior with the ENABLE_TOOL_SEARCH environment variable:

Value	Behavior
`auto`	Activates when MCP tools exceed 10% of context (default)
`auto:5`	Activates at a custom 5% threshold
`true`	Always enabled
`false`	Disabled, all MCP tools loaded upfront

bash

# Use a custom threshold
ENABLE_TOOL_SEARCH=auto:5 claude

This becomes essential as your MCP server collection grows.

Security Considerations

MCP servers are powerful, which means they demand careful handling.

Only Use Trusted Servers

MCP servers can access your system, read files, execute commands, and connect to external services. Only install servers from sources you trust. Be especially cautious with servers that fetch untrusted content, as these can expose you to prompt injection risks.

Key security practices:

Review before installing: Check the server's source code or documentation before adding it
Use environment variables for secrets: Never hardcode API keys in configuration files. Use --env flags or ${VAR} expansion in .mcp.json
Scope credentials tightly: Use read-only database connections for query servers. Grant the minimum permissions necessary
Prefer project scope for team servers: Project-scoped servers in .mcp.json require approval before first use, adding a security checkpoint
Monitor output limits: Set MAX_MCP_OUTPUT_TOKENS to prevent unexpectedly large responses from consuming your context (default is 25,000 tokens)
Configure startup timeouts: Use MCP_TIMEOUT to control how long Claude Code waits for a server to start (e.g., MCP_TIMEOUT=10000 for 10 seconds)

For organizations, Claude Code supports managed MCP configuration through managed-mcp.json deployed to system directories. This gives IT administrators exclusive control over which MCP servers employees can use, with allowlists and denylists for fine-grained policy enforcement.

Configure and Use an MCP Server

intermediate20 min

In this exercise, you will connect a real MCP server to Claude Code and use it in a conversation.

Part 1: Add a Filesystem Server

Choose a project directory you want to give Claude scoped access to
Add the filesystem MCP server:

bash

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

Verify it's connected:

bash

claude mcp list

Start Claude Code and run /mcp to confirm the server shows a green status
Ask Claude to use the filesystem tools: "List all files in the project root using the filesystem server"

Part 2: Try a Remote Server (Optional)

Add the GitHub MCP server:

bash

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Inside Claude Code, run /mcp and authenticate with your GitHub account
Ask Claude: "Show me my most recent open pull requests"

Part 3: Explore Configuration

Run claude mcp get filesystem to inspect the server configuration
Try adding the same server with --scope user and verify it appears across projects
Remove the duplicate with claude mcp remove filesystem

Reflection questions:

How does the MCP server extend what Claude Code can do compared to its built-in tools?
What security considerations would you weigh before adding a database MCP server with write access?
When would you use project scope vs. user scope for a server?

Key Takeaway

MCP transforms Claude Code from a coding assistant into a fully connected development hub.

The key concepts to remember:

MCP is the universal connector: One protocol, hundreds of integrations -- databases, APIs, monitoring, project management, and more
Three transports: Use stdio for local tools, HTTP for remote services, and avoid SSE for new integrations
Configuration scopes matter: Use local for personal tools, project for team-shared servers (committed to git), and user for cross-project utilities
Security is non-negotiable: Only install trusted servers, use environment variables for secrets, and grant minimum permissions
Tool Search keeps context clean: As your server collection grows, Tool Search dynamically loads only the tools Claude needs

Start with one or two servers that match your daily workflow -- GitHub, a database, or your project management tool -- and expand from there.

Next Steps

You now know how to extend Claude Code's reach to virtually any tool or service. In the next lesson, we'll explore hooks and automation -- customizing Claude Code's behavior with event-driven scripts that run before, during, and after tool execution.

Resources:

MCP specification and server registry: modelcontextprotocol.io
Official server list: github.com/modelcontextprotocol/servers
MCP SDK quickstart: modelcontextprotocol.io/quickstart/server
Claude Code MCP documentation: code.claude.com/docs/en/mcp

MCP Servers — Connecting External Tools

This lesson teaches you how MCP works, how to configure servers, and how to extend Claude Code's capabilities to reach any tool or data source your work demands.

Learning Objectives

Understand MCP architecture and how Claude Code communicates with external tools
Configure MCP servers using the CLI and JSON configuration
Choose the correct transport type (stdio, HTTP, SSE) for your use case
Connect popular integrations like GitHub, Slack, databases, and monitoring tools
Manage server scopes for personal, project-wide, and team-shared configurations
Apply security best practices when working with MCP servers

What Is MCP?

Before MCP, connecting an AI assistant to your tools meant fragile, one-off integrations. MCP standardizes this into a clean architecture:

Claude Code (Client) <--MCP Protocol--> Server <--API/SDK--> External Service

An MCP server exposes three types of capabilities:

Tools: Actions Claude can invoke (e.g., "create a GitHub issue," "query the database")
Resources: Data Claude can read (e.g., files, database schemas, API documentation)
Prompts: Predefined prompt templates that appear as slash commands in Claude Code

Transport Types

MCP servers communicate with Claude Code through different transport mechanisms. The transport you choose depends on where the server runs.

Transport	How It Works	Best For	Example
stdio	Claude spawns the server as a local child process	Local tools, CLI wrappers, custom scripts	npx -y @modelcontextprotocol/server-filesystem
HTTP (Streamable)	Remote server over standard HTTP	Cloud-hosted services, production deployments	https://mcp.notion.com/mcp
SSE (deprecated)	Remote server using Server-Sent Events	Legacy remote servers (prefer HTTP instead)	https://mcp.asana.com/sse

stdio is the most common transport for local tools. Claude Code launches the server process, communicates over stdin/stdout, and manages its lifecycle automatically.

HTTP is the recommended transport for remote servers. It uses standard HTTP requests and is the most widely supported option for cloud-based services.

SSE (Server-Sent Events) is a legacy transport for remote servers. It still works but has been deprecated in favor of HTTP. Use HTTP for new integrations where available.

Installing MCP Servers

Claude Code provides the claude mcp add command for configuring servers. The exact syntax depends on the transport type.

Adding a Remote HTTP Server

Run the add command with the HTTP transport

bash

claude mcp add --transport http <name> <url>

For example, to connect the Notion MCP server:

bash

claude mcp add --transport http notion https://mcp.notion.com/mcp

If the server requires authentication headers, pass them with --header:

bash

claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Verify the server is connected

bash

claude mcp list

Or inside Claude Code, run /mcp to see all connected servers and their status.

Adding a Local stdio Server

Run the add command with the stdio transport

Use -- (double dash) to separate Claude's flags from the server command:

bash

claude mcp add --transport stdio <name> -- <command> [args...]

For example, adding a filesystem server:

bash

claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

Pass environment variables with --env:

bash

claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=your_key \
  -- npx -y airtable-mcp-server

Confirm the server starts correctly

Run /mcp inside Claude Code. You should see the server listed with a green status indicator.

Windows Users: Use cmd /c Wrapper

On native Windows (not WSL), local MCP servers that use npx require the cmd /c wrapper. Without it, you'll get "Connection closed" errors because Windows cannot directly execute npx.

bash

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Option Ordering Matters

All flags (--transport, --env, --scope, --header) must come before the server name. The -- separates the server name from the command passed to the MCP server. For example:

bash

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080

This prevents conflicts between Claude Code's flags and the server's flags.

Managing Servers

Once configured, manage your servers with these commands:

bash

# List all configured servers
claude mcp list
 
# Get details for a specific server
claude mcp get github
 
# Remove a server
claude mcp remove github
 
# Inside Claude Code, check status and authenticate
/mcp

Configuration Scopes

MCP servers can be configured at three scope levels, controlling who sees the server and where the config is stored.

Scope	Stored In	Visible To	Use Case
local (default)	~/.claude.json (under project path)	Only you, only this project	Personal tools, experimental servers, sensitive credentials
project	.mcp.json in project root	Everyone on the team (committed to git)	Shared project tools, team-wide integrations
user	~/.claude.json (global)	Only you, across all projects	Personal utilities used in every project

Specify the scope with --scope:

bash

# Local (default) — private to you, this project only
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
 
# Project — shared with the team via .mcp.json
claude mcp add --transport http sentry --scope project https://mcp.sentry.dev/mcp
 
# User — available in all your projects
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Project-Scoped Configuration File

When you use --scope project, Claude Code creates or updates a .mcp.json file in the project root. This file is designed to be committed to version control:

json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "postgresql://readonly:pass@db.example.com:5432/app"],
      "env": {}
    }
  }
}

The .mcp.json file supports environment variable expansion, allowing teams to share configuration without hardcoding secrets:

json

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Use ${VAR} for required variables and ${VAR:-default} for variables with fallback values.

Scope Precedence

Popular MCP Servers

The MCP ecosystem has grown rapidly. Here are some of the most useful servers for development workflows:

OAuth Authentication

Many cloud-based MCP servers require OAuth 2.0 authentication. Claude Code handles this flow for you.

Add the server

bash

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Authenticate inside Claude Code

Run /mcp, select the server, and choose "Authenticate." A browser window opens for you to complete the login flow.

Start using the server

Authentication tokens are stored securely and refreshed automatically. You can revoke access anytime via the /mcp menu.

For servers that don't support automatic OAuth discovery, you may need to pre-register an OAuth app and provide credentials manually:

bash

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

The --client-secret flag prompts for the secret with masked input so it never appears in your shell history.

Building Custom MCP Servers

When no existing server covers your needs, you can build your own. The MCP SDK is available for both TypeScript and Python.

A minimal MCP server exposes tools that Claude can discover and invoke. Here is a simplified TypeScript example showing the structure:

typescript

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
const server = new McpServer({
  name: "weather-server",
  version: "1.0.0",
});
 
// Define a tool
server.tool(
  "get_weather",
  "Get current weather for a city",
  { city: { type: "string", description: "City name" } },
  async ({ city }) => {
    const data = await fetch(`https://api.weather.com/v1/current?q=${city}`);
    const weather = await data.json();
    return {
      content: [{ type: "text", text: JSON.stringify(weather, null, 2) }],
    };
  }
);
 
// Connect via stdio transport
const transport = new StdioServerTransport();
await server.connect(transport);

After building the server, register it with Claude Code:

bash

claude mcp add --transport stdio weather -- node /path/to/weather-server.js

MCP Tool Search

When you have many MCP servers configured, loading every tool into context wastes tokens. Claude Code solves this with Tool Search -- a system that dynamically loads tools on demand.

Tool Search activates automatically when your MCP tool definitions exceed 10% of the context window. Instead of preloading all tools, Claude searches for the relevant ones when needed.

You can control this behavior with the ENABLE_TOOL_SEARCH environment variable:

Value	Behavior
`auto`	Activates when MCP tools exceed 10% of context (default)
`auto:5`	Activates at a custom 5% threshold
`true`	Always enabled
`false`	Disabled, all MCP tools loaded upfront

bash

# Use a custom threshold
ENABLE_TOOL_SEARCH=auto:5 claude

This becomes essential as your MCP server collection grows.

Security Considerations

MCP servers are powerful, which means they demand careful handling.

Only Use Trusted Servers

Key security practices:

Review before installing: Check the server's source code or documentation before adding it
Use environment variables for secrets: Never hardcode API keys in configuration files. Use --env flags or ${VAR} expansion in .mcp.json
Scope credentials tightly: Use read-only database connections for query servers. Grant the minimum permissions necessary
Prefer project scope for team servers: Project-scoped servers in .mcp.json require approval before first use, adding a security checkpoint
Monitor output limits: Set MAX_MCP_OUTPUT_TOKENS to prevent unexpectedly large responses from consuming your context (default is 25,000 tokens)
Configure startup timeouts: Use MCP_TIMEOUT to control how long Claude Code waits for a server to start (e.g., MCP_TIMEOUT=10000 for 10 seconds)

Configure and Use an MCP Server

intermediate20 min

In this exercise, you will connect a real MCP server to Claude Code and use it in a conversation.

Part 1: Add a Filesystem Server

Choose a project directory you want to give Claude scoped access to
Add the filesystem MCP server:

bash

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

Verify it's connected:

bash

claude mcp list

Start Claude Code and run /mcp to confirm the server shows a green status
Ask Claude to use the filesystem tools: "List all files in the project root using the filesystem server"

Part 2: Try a Remote Server (Optional)

Add the GitHub MCP server:

bash

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Inside Claude Code, run /mcp and authenticate with your GitHub account
Ask Claude: "Show me my most recent open pull requests"

Part 3: Explore Configuration

Run claude mcp get filesystem to inspect the server configuration
Try adding the same server with --scope user and verify it appears across projects
Remove the duplicate with claude mcp remove filesystem

Reflection questions:

How does the MCP server extend what Claude Code can do compared to its built-in tools?
What security considerations would you weigh before adding a database MCP server with write access?
When would you use project scope vs. user scope for a server?

Key Takeaway

MCP transforms Claude Code from a coding assistant into a fully connected development hub.

The key concepts to remember:

MCP is the universal connector: One protocol, hundreds of integrations -- databases, APIs, monitoring, project management, and more
Three transports: Use stdio for local tools, HTTP for remote services, and avoid SSE for new integrations
Configuration scopes matter: Use local for personal tools, project for team-shared servers (committed to git), and user for cross-project utilities
Security is non-negotiable: Only install trusted servers, use environment variables for secrets, and grant minimum permissions
Tool Search keeps context clean: As your server collection grows, Tool Search dynamically loads only the tools Claude needs

Start with one or two servers that match your daily workflow -- GitHub, a database, or your project management tool -- and expand from there.

Next Steps

Resources:

MCP specification and server registry: modelcontextprotocol.io
Official server list: github.com/modelcontextprotocol/servers
MCP SDK quickstart: modelcontextprotocol.io/quickstart/server
Claude Code MCP documentation: code.claude.com/docs/en/mcp