The Complete MCP Guide — The Standard Protocol That Gives Your AI Agent Hands and Feet [2026]

Claude ──custom integration──▶ Notion
Claude ──custom integration──▶ GitHub
Claude ──custom integration──▶ Slack
GPT-4  ──different custom────▶ Notion
GPT-4  ──different custom────▶ GitHub
                               (same service, built twice)

Notion MCP Server ◀──MCP standard──▶ Claude
                  ◀──MCP standard──▶ GPT-4
                  ◀──MCP standard──▶ Cursor
                  ◀──MCP standard──▶ Any AI client

[Before MCP]
AI clients: Claude, GPT-4, Gemini, Cursor (4 clients)
External tools: DB, GitHub, Slack, Figma, Gmail (5 services)
Custom integrations needed: 4 × 5 = 20

[After MCP]
Each service builds one MCP server
MCP servers: DB, GitHub, Slack, Figma, Gmail (5 servers)
AI clients connect via MCP (4 clients)
Total integrations needed: 5 + 4 = 9

┌─────────────────────────────────────────────────┐
│                  MCP Ecosystem                    │
│                                                   │
│  ┌──────────────┐    MCP Protocol    ┌──────────┐ │
│  │  MCP Client  │◄──────────────────▶│MCP Server│ │
│  │              │   (JSON-RPC 2.0)   │          │ │
│  │ Claude       │                   │ DB server │ │
│  │ Cursor       │                   │ GitHub srv│ │
│  │ My Agent     │                   │ My API    │ │
│  └──────────────┘                   └─────┬─────┘ │
│                                           │       │
│                                    ┌──────▼──────┐ │
│                                    │External Svc  │ │
│                                    │(DB, APIs...) │ │
│                                    └─────────────┘ │
└─────────────────────────────────────────────────┘

# Tool = a function the AI calls
# Examples: web search, DB query, file save
@mcp.tool()
def get_weather(city: str) -> str:
    """Returns the current weather for a given city."""
    # Real implementation: call a weather API
    return f"{city}: Sunny, 22°C"

# Resource = data the AI reads as context
# Examples: file contents, DB records, config info
@mcp.resource("config://app-settings")
def get_app_config() -> str:
    """Returns application configuration."""
    return json.dumps({"version": "1.0", "env": "production"})

# Prompt = frequently used prompts stored on the server
# Examples: code review template, report writing format
@mcp.prompt()
def code_review_prompt(language: str, code: str) -> str:
    """Generates a prompt for code review."""
    return f"""
Please review the following {language} code:
```{language}
{code}

# my_mcp_server.py
from fastmcp import FastMCP
import json
import os
from datetime import datetime
# Initialize MCP server
mcp = FastMCP(
    name="My First MCP Server",
    description="MCP server providing weather checks, calculations, and memo storage"
)
# ── Tool 1: Weather Lookup ────────────────────────────
@mcp.tool()
async def get_weather(city: str) -> str:
    """
    Look up current weather for a city.
    Examples: get_weather("Tokyo"), get_weather("New York")
    """
    # Production: wire to OpenWeather API or similar
    # Demo data for this tutorial
    weather_data = {
        "seoul": {"temp": 18, "condition": "Sunny", "humidity": 55},
        "tokyo": {"temp": 22, "condition": "Cloudy", "humidity": 70},
        "new york": {"temp": 15, "condition": "Rainy", "humidity": 85},
        "london": {"temp": 12, "condition": "Foggy", "humidity": 90},
    }
    city_lower = city.lower()
    if city_lower in weather_data:
        w = weather_data[city_lower]
        return f"{city} weather: {w['condition']}, {w['temp']}°C, humidity {w['humidity']}%"
    return f"No weather data found for '{city}'."
# ── Tool 2: Calculator ───────────────────────────────
@mcp.tool()
def calculate(expression: str) -> str:
    """
    Evaluate a math expression.
    Examples: "2 + 2 * 10", "sqrt(144)", "(100 - 20) / 4"
    """
    import math
    safe_env = {
        "__builtins__": {},
        "sqrt": math.sqrt,
        "pow": math.pow,
        "abs": abs,
        "round": round,
        "pi": math.pi,
        "e": math.e,
    }
    try:
        result = eval(expression, safe_env)
        return f"{expression} = {result}"
    except Exception as e:
        return f"Calculation error: {str(e)}"
# ── Tool 3: Save / Retrieve Memos ───────────────────
MEMO_FILE = "memos.json"
def _load_memos() -> dict:
    if os.path.exists(MEMO_FILE):
        with open(MEMO_FILE, "r") as f:
            return json.load(f)
    return {}
def _save_memos(memos: dict):
    with open(MEMO_FILE, "w") as f:
        json.dump(memos, f, indent=2)
@mcp.tool()
def save_memo(title: str, content: str) -> str:
    """Save a memo with a title and content."""
    memos = _load_memos()
    memos[title] = {
        "content": content,
        "created_at": datetime.now().isoformat()
    }
    _save_memos(memos)
    return f"✅ Memo saved: '{title}'"
@mcp.tool()
def get_memo(title: str) -> str:
    """Retrieve a saved memo by title."""
    memos = _load_memos()
    if title in memos:
        memo = memos[title]
        return f"📝 [{title}]\n{memo['content']}\n\nSaved at: {memo['created_at']}"
    return f"No memo found for '{title}'. Existing memos: {list(memos.keys())}"
@mcp.tool()
def list_memos() -> str:
    """List all saved memos."""
    memos = _load_memos()
    if not memos:
        return "No memos saved yet."
    items = [f"- {title} ({m['created_at'][:10]})" for title, m in memos.items()]
    return "📋 Saved memos:\n" + "\n".join(items)
# ── Resource: Server Status ──────────────────────────
@mcp.resource("server://status")
def get_server_status() -> str:
    """Returns current server status and available tools."""
    return json.dumps({
        "status": "running",
        "version": "1.0.0",
        "tools": ["get_weather", "calculate", "save_memo", "get_memo", "list_memos"],
        "timestamp": datetime.now().isoformat()
    })
# ── Prompt: Weather Report Template ─────────────────
@mcp.prompt()
def weather_report_prompt(cities: str) -> str:
    """Prompt template for generating a multi-city weather comparison report."""
    return f"""
Check the weather for these cities and write a comparison report: {cities}
Report format:
1. Current weather status for each city
2. Best weather city recommendation
3. Travel / outdoor activity suitability rating
Use the available tools to fetch real weather data before writing.
"""
# ── Run the Server ───────────────────────────────────
if __name__ == "__main__":
    # stdio mode: connects locally to Claude Desktop, Cursor, etc.
    mcp.run()
    # HTTP mode (for remote deployment):
    # mcp.run(transport="streamable-http", host="0.0.0.0", port=8080)

# Start the server (stdio mode)
python my_mcp_server.py
# Test with MCP Inspector (separate terminal)
npx @modelcontextprotocol/inspector python my_mcp_server.py

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%/Claude/claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/absolute/path/to/my_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path"
      }
    }
  }
}

// .cursor/mcp.json (project root)
{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["my_mcp_server.py"]
    }
  }
}

# langchain_with_mcp.py
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_anthropic import ChatAnthropic
from langgraph.prebuilt import create_react_agent
async def main():
    # Initialize MCP client
    async with MultiServerMCPClient(
        {
            "my-server": {
                "command": "python",
                "args": ["my_mcp_server.py"],
                "transport": "stdio",
            }
        }
    ) as client:
        # MCP tools are auto-converted to LangChain tools
        tools = await client.get_tools()
        print(f"✅ {len(tools)} MCP tools loaded")
        for tool in tools:
            print(f"  - {tool.name}: {tool.description[:50]}...")
        # Wire MCP tools into a LangGraph agent
        llm = ChatAnthropic(model="claude-sonnet-4-20250514")
        agent = create_react_agent(llm, tools)
        # Run the agent
        result = await agent.ainvoke({
            "messages": [("user", "Check the weather in Tokyo and New York, then save a memo comparing them.")]
        })
        print("\n📌 Agent response:")
        print(result["messages"][-1].content)
import asyncio
asyncio.run(main())

pip install langchain-mcp-adapters langchain-anthropic langgraph

# Cloud deployment (HTTP mode)
from fastmcp import FastMCP
import os
mcp = FastMCP("My Cloud MCP Server")
# ... tool definitions are identical ...
if __name__ == "__main__":
    mcp.run(
        transport="streamable-http",
        host="0.0.0.0",
        port=int(os.getenv("PORT", 8080))
    )

# Dockerfile
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["python", "my_mcp_server.py"]

# requirements.txt
fastmcp>=3.0
httpx
python-dotenv

# Deploy
railway up
# Connect to Claude Desktop via HTTP after deploying:
# claude_desktop_config.json:
# {
#   "mcpServers": {
#     "my-cloud-server": {
#       "url": "https://your-app.up.railway.app/mcp",
#       "transport": "streamable-http"
#     }
#   }
# }

# ❌ Dangerous: write access for untrusted agents
@mcp.tool()
def execute_sql(query: str) -> str:
    """Execute an SQL query."""
    return db.execute(query)  # DELETE, DROP possible!
# ✅ Safe: read only
@mcp.tool()
def search_data(keyword: str) -> str:
    """Search data by keyword (read-only)."""
    return db.execute(
        "SELECT * FROM data WHERE content LIKE ? LIMIT 10",

@mcp.tool()
def save_file(filename: str, content: str) -> str:
    """Save content to a file."""
    # Prevent path traversal
    if ".." in filename or "/" in filename or "\\" in filename:
        return "Error: invalid filename."
    # Enforce file size limit
    if len(content) > 1_000_000:  # 1MB
        return "Error: file too large (max 1MB)."
    safe_path = os.path.join("./allowed_dir", os.path.basename(filename))
    with open(safe_path, "w") as f:
        f.write(content)
    return f"✅ Saved: {filename}"

# ❌ Never do this
API_KEY = "sk-1234567890"  # hardcoded in source
# ✅ Inject via environment variable
import os
API_KEY = os.getenv("MY_API_KEY")
if not API_KEY:
    raise ValueError("MY_API_KEY environment variable is not set.")