MCP Integration

Elementary

Connecting external tools and data sources with Model Context Protocol

30 min read

What is MCP (Model Context Protocol)?

MCP is an open-source standard protocol for connecting AI models with external tools and data sources. It was developed and led by Anthropic, and through MCP, Claude Code can directly integrate with a wide variety of services and tools.

ℹ️Understanding MCP the easy way

Think of MCP as a "USB port that connects external tools to AI."

For example, if you connect the Notion MCP to Claude Code, you can simply say "Find meeting notes in Notion" and the AI will search Notion directly. If you connect the GitHub MCP, you can just say "Show me the recent PR list."

Without MCP, Claude Code can only work with code files, but with MCP connected, the AI can directly interact with external services such as Notion, GitHub, Slack, databases, and more.

Core Concepts of MCP

Server: The side that provides tools and data (e.g., Notion, GitHub, Sentry)
Client: The side that connects to servers and uses tools (Claude Code)
Tools: Executable functions provided by an MCP server
Resources: Readable data provided by an MCP server
Prompts: Predefined prompt templates provided by an MCP server

With MCP, Claude Code can directly call external APIs, query databases, or interact with SaaS tools.

3 Transport Methods

There are 3 transport methods for connecting to MCP servers.

💡Which transport method should you choose?

HTTP: Use this in most cases. Most official MCP servers like Notion and Linear use HTTP
SSE: Only used with older MCP servers. If you're just getting started, you can ignore this
Stdio: Runs directly on your local machine without an internet connection. Use this when accessing local files or databases

If you're unsure, choose HTTP.

HTTP (Recommended)

The most recommended method. Connects to remote MCP servers via HTTP.

# Connect to Notion MCP server
claude mcp add --transport http notion https://mcp.notion.com/mcp
 
# Connect to Linear MCP server
claude mcp add --transport http linear https://mcp.linear.app/sse

SSE (Legacy)

Server-Sent Events method. Used with older versions of MCP servers.

# Connect to Asana MCP server
claude mcp add --transport sse asana https://mcp.asana.com/sse

Stdio (Local)

Runs MCP server processes directly on your local machine.

# Filesystem MCP server
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir
 
# GitHub MCP server
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github
 
# PostgreSQL MCP server
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb

Managing MCP Servers

List servers

# List all configured MCP servers
claude mcp list

Server details

# View configuration details for a specific server
claude mcp get notion

Remove a server

# Remove an MCP server connection
claude mcp remove notion

Reset project choices

# Reset per-project MCP tool permissions
claude mcp reset-project-choices

Installation Scope

MCP servers can be installed at 3 different scopes.

ℹ️What is project scope?

Scope determines where the MCP server configuration applies.

project (project scope): Used only in the current project. Can be shared with team members
user (user scope): Used across all projects on your machine. Personal configuration

For example, if you only use Notion in a specific project, set it with --scope project. If you use GitHub across all projects, set it with --scope user. When starting out, using the default (user) is fine.

Scope	Config File	Applies To	When to Use
local	`~/.claude.json`	Current user, all projects	Personal tools (default)
project	`.mcp.json`	Current project only	Team-shared tools
user	User settings	Current user, all projects	Per-user settings

# Install at project scope (shared with team)
claude mcp add --scope project notion --transport http https://mcp.notion.com/mcp
 
# Install at local scope (personal use, default)
claude mcp add --scope local github --transport stdio -- npx -y @modelcontextprotocol/server-github

.mcp.json File Format

By creating a .mcp.json file in your project, all team members can use the same MCP servers.

{
  "mcpServers": {
    "notion": {
      "transport": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./docs"]
    }
  }
}

Notes for Windows Users

When using Stdio-based MCP servers on Windows (WSL2), you may need a cmd /c wrapper.

# When running npx-based MCP servers on Windows
claude mcp add --transport stdio myserver -- cmd /c npx -y @some/mcp-server

This is due to path differences between WSL2 and native Windows Node.js. If you're running directly inside WSL2, the wrapper is not needed.

OAuth 2.0 Authentication

Some MCP servers support OAuth 2.0 authentication. On the first connection, a browser window will automatically open to guide you through the authentication process.

Example Services with Auth Support

Sentry: Error tracking and monitoring
GitHub: Repository, issue, and PR management
Linear: Project management
Notion: Documents and databases

# Sentry MCP server (OAuth authentication)
claude mcp add --transport http sentry https://mcp.sentry.dev/sse
 
# On first use, a browser opens and you log in with your Sentry account
# After authentication, the token is automatically saved

Tool Search

Tool Search is a feature that allows Claude Code to automatically find and activate the MCP tools it needs.

Key Features

Auto-activation: When an MCP server provides many tools, only the needed ones are searched and loaded rather than loading all tools into context
95% token savings: Avoids sending hundreds of tool definitions every time, improving cost and speed
Transparent operation: Works automatically without any user configuration

Control via Environment Variables

# Disable Tool Search
export ENABLE_TOOL_SEARCH=false
 
# Enable Tool Search (default)
export ENABLE_TOOL_SEARCH=true

Using MCP Prompts as Commands

Prompts provided by MCP servers can be used like slash commands.

Format

/mcp__servername__promptname

Examples

# Use the Notion server's search prompt
/mcp__notion__search

# Use the GitHub server's PR review prompt
/mcp__github__review-pr

MCP prompts provide predefined workflows for each server, allowing you to execute complex tasks with simple commands.

MCP Resources (@ Mentions)

MCP Resources can be mentioned with the @ symbol to include them in the context.

# Include a Notion page in the context
@notion:page/project-requirements

# Reference a GitHub issue
@github:issue/123

When you mention a resource, the data is automatically included in Claude's context, allowing you to reference external data without copy-pasting.

Using Claude Code as an MCP Server

Claude Code itself can be run as an MCP server, allowing other MCP clients to connect to it.

# Run Claude Code as an MCP server
claude mcp serve

This allows other AI tools or automation systems to call Claude Code's capabilities via the MCP protocol. For example, you can connect to Claude Code from VS Code's MCP client or other agents.

Managed MCP (For Organizations)

MCP servers can be managed at the organization level. Through the managed-mcp.json file, you can deploy the same MCP server configuration to all users within an organization.

managed-mcp.json

{
  "mcpServers": {
    "internal-api": {
      "transport": "http",
      "url": "https://mcp.internal.company.com/api",
      "required": true
    },
    "sentry": {
      "transport": "http",
      "url": "https://mcp.sentry.dev/sse",
      "required": false
    }
  }
}

Features

required: true: Mandatory server that users cannot disable
required: false: Users can optionally enable/disable
Centralized management: IT administrators can manage all MCP connections across the organization
Security control: Can restrict usage to only approved MCP servers

Practical MCP Configuration Examples

MCP Setup for Full-Stack Developers

# Project management
claude mcp add --transport http linear https://mcp.linear.app/sse
 
# Document management
claude mcp add --transport http notion https://mcp.notion.com/mcp
 
# Error monitoring
claude mcp add --transport http sentry https://mcp.sentry.dev/sse
 
# Local database
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb
 
# File browsing
claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem ./docs

Verify Configuration

# Check status of all MCP servers
claude mcp list
 
# Test connection to a specific server
claude mcp get linear

Top 10 Popular MCP Servers

Among the many MCP servers available, here are the 10 most popular and useful ones. Choose the servers that match your project needs to extend Claude Code's capabilities.

Rank	Server	Purpose	Transport	Installation Command
1	GitHub	Repository, issue, and PR management	Stdio	`claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github`
2	Notion	Documents, databases, and wiki integration	HTTP	`claude mcp add --transport http notion https://mcp.notion.com/mcp`
3	Slack	Messaging, channel management, search	Stdio	`claude mcp add --transport stdio slack -- npx -y @anthropic-ai/mcp-server-slack`
4	Sentry	Error tracking, performance monitoring	HTTP	`claude mcp add --transport http sentry https://mcp.sentry.dev/sse`
5	Playwright	Browser automation, E2E testing	Stdio	`claude mcp add --transport stdio playwright -- npx -y @anthropic-ai/mcp-server-playwright`
6	PostgreSQL	Database querying and management	Stdio	`claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/mydb`
7	Filesystem	Extended local filesystem access	Stdio	`claude mcp add --transport stdio filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/dir`
8	Linear	Project/issue management, sprint tracking	HTTP	`claude mcp add --transport http linear https://mcp.linear.app/sse`
9	Figma	Design file viewing, component inspection	Stdio	`claude mcp add --transport stdio figma -- npx -y @anthropic-ai/mcp-server-figma`
10	Puppeteer	Web scraping, screenshots, PDF generation	Stdio	`claude mcp add --transport stdio puppeteer -- npx -y @anthropic-ai/mcp-server-puppeteer`

Tip: All Stdio-based servers can be run instantly with npx -y without installation. Register frequently used servers in .mcp.json to share them with your team.

Building Your Own MCP Server

If you need functionality that existing MCP servers don't provide, you can build your own MCP server. Below is an example of creating a simple MCP server in TypeScript that provides a weather lookup tool (get_weather).

Step 1: Initialize the Project

# Create project directory and initialize
mkdir my-weather-mcp && cd my-weather-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init

Step 2: Write the Server Code

Create the src/index.ts file.

// src/index.ts
// Main file for the MCP server.
// When Claude Code calls the "get_weather" tool,
// this server returns weather information.
 
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
// Create an MCP server instance
const server = new McpServer({
  name: "weather-server",       // Server name (displayed in Claude Code)
  version: "1.0.0",             // Server version
});
 
// Register the "get_weather" tool
// This tool takes a city name and returns weather information
server.tool(
  "get_weather",                              // Tool name
  "Looks up the current weather for a given city",  // Tool description (referenced by Claude)
  {
    city: z.string().describe("City name to look up weather for (e.g., Seoul, Tokyo)"),
  },
  async ({ city }) => {
    // In a real service, you would call a weather API here
    // This example returns simple dummy data
    const weatherData: Record<string, { temp: number; condition: string }> = {
      Seoul: { temp: 12, condition: "Clear" },
      Tokyo: { temp: 15, condition: "Cloudy" },
      "New York": { temp: 8, condition: "Rainy" },
    };
 
    const weather = weatherData[city];
 
    if (!weather) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Weather data not found for city "${city}".`,
          },
        ],
      };
    }
 
    return {
      content: [
        {
          type: "text" as const,
          text: `Current weather in ${city}: ${weather.temp}°C, ${weather.condition}`,
        },
      ],
    };
  }
);
 
// Start the server (using Stdio transport)
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP server has started");  // Log output to stderr
}
 
main().catch(console.error);

Step 3: Build and Verify

# Build TypeScript
npx tsc
 
# Verify it runs (press Ctrl+C to stop)
node dist/index.js

Step 4: Register with Claude Code

# Register your custom MCP server with Claude Code
claude mcp add --transport stdio weather-server -- node /absolute/path/to/my-weather-mcp/dist/index.js
 
# Verify registration
claude mcp list
 
# Test usage (inside Claude Code)
# Type "What's the weather in Seoul?" and the get_weather tool will be called automatically

Practical Tips

Error logs should always use console.error(). console.log() conflicts with MCP protocol messages.
When integrating external APIs, pass API keys as environment variables: claude mcp add ... -e API_KEY=xxx
For team sharing, register in .mcp.json and commit to Git.
For debugging, check the server status with claude mcp get weather-server.

By leveraging MCP effectively, you can expand Claude Code from a simple coding tool into an integrated development platform.

Was this helpful?

Related:Sub-Agents Hooks System