模型上下文协议工具集成标准

Without MCP: "I need to write code to make my tool work with Claude,
              then rewrite it for GPT, then again for Gemini..."

With MCP:    "I build an MCP server once. Claude, GPT, Gemini — they
              all connect to the same server using the same protocol."

5 tools × 4 AI models = 20 custom integrations to build and maintain

5 tools (each as an MCP server)  +  4 AI clients (each MCP-compatible)
= 9 total things to build

┌─────────────────────────────────────────────────────────────────┐
│                         YOUR APPLICATION                         │
│                                                                  │
│  ┌──────────────────┐            ┌─────────────────────────┐    │
│  │    MCP CLIENT     │           │      Claude API          │    │
│  │  (mcp_client.py) │◄─────────►│  (or GPT / Gemini / ...) │   │
│  └────────┬─────────┘            └─────────────────────────┘    │
│           │                                                      │
│     MCP Protocol                                                 │
│     (JSON-RPC over stdio / SSE / WebSocket)                     │
│           │                                                      │
│  ┌────────▼─────────┐                                           │
│  │    MCP SERVER     │                                           │
│  │  (mcp_server.py) │                                           │
│  │                  │                                           │
│  │  Tools exposed:  │                                           │
│  │   • calculate    │                                           │
│  │   • get_weather  │                                           │
│  │   • save_note    │                                           │
│  │   • get_note     │                                           │
│  │   • list_notes   │                                           │
│  │   • get_datetime │                                           │
│  │   • word_count   │                                           │
│  └──────────────────┘                                           │
└─────────────────────────────────────────────────────────────────┘

User types: "What is sqrt(144) + 10^2?"
                    │
                    ▼
           MCP Client sends to Claude API
           (includes list of tools discovered from MCP server)
                    │
                    ▼
         Claude thinks: "I need the calculator tool"
         Claude responds: tool_use { name: "calculate", input: {...} }
                    │
                    ▼
         MCP Client routes to MCP Server via call_tool()
         Server executes the calculation
         Server returns: "Result: 112"
                    │
                    ▼
         MCP Client sends tool_result back to Claude
                    │
                    ▼
         Claude responds: "sqrt(144) is 12, and 10² is 100, so the answer is 112."
                    │
                    ▼
         User sees the final answer

// Client → Server: "What tools do you have?"
{ "jsonrpc": "2.0", "method": "tools/list", "id": 1 }

// Server → Client: "Here are my tools"
{ "jsonrpc": "2.0", "result": { "tools": [...] }, "id": 1 }

// Client → Server: "Run the calculator"
{ "jsonrpc": "2.0", "method": "tools/call",
  "params": { "name": "calculate", "arguments": { "expression": "sqrt(144)" } },
  "id": 2 }

// Server → Client: "Here's the result"
{ "jsonrpc": "2.0", "result": { "content": [{ "type": "text", "text": "Result: 12" }] }, "id": 2 }

mcp_explained/
│
├── README.md                    ← You are here
├── pyproject.toml               ← Project dependencies (uv)
├── requirements.txt             ← Same deps for pip users
├── .env.example                 ← API key template
├── .gitignore
│
├── server/
│   └── mcp_server.py            ← THE MCP SERVER
│                                   Exposes 7 tools via stdio transport
│                                   Any MCP-compatible AI can connect to this
│
├── client/
│   └── mcp_client.py            ← THE MCP CLIENT
│                                   Connects to server, uses Claude + MCP
│                                   Interactive CLI + scripted demo mode
│
├── examples/
│   ├── 01_without_mcp.py        ← Traditional approach (hardcoded tools)
│   └── 02_with_mcp.py           ← MCP approach (dynamic discovery)
│
└── data/
    └── notes.json               ← Persisted notes (created at runtime)

git clone https://github.com/shashipk/mcp_explained.git
cd mcp_explained

uv sync

python3 -m venv .venv
source .venv/bin/activate      # macOS/Linux
pip install -r requirements.txt

cp .env.example .env

ANTHROPIC_API_KEY=sk-ant-api03-your-actual-key-here

# Check that all packages are importable
uv run python -c "import mcp, anthropic, dotenv, rich; print('All OK')"
# Expected: All OK

# Confirm your API key loads
uv run python -c "
from dotenv import load_dotenv; import os
load_dotenv('.env', override=True)
key = os.environ.get('ANTHROPIC_API_KEY', '')
print('Key OK' if key.startswith('sk-ant') else 'Key missing — check your .env')
"

1. Read "What is MCP?" and "Why Do We Need MCP?" above
         ↓
2. Run Example 1 (without MCP) — see the problem
   uv run python examples/01_without_mcp.py
         ↓
3. Run Example 2 (with MCP) — see the solution
   uv run python examples/02_with_mcp.py
         ↓
4. Compare the two files side by side in your editor
   Open: examples/01_without_mcp.py  vs  examples/02_with_mcp.py
         ↓
5. Read the server code with comments
   Open: server/mcp_server.py
         ↓
6. Read the client code with comments
   Open: client/mcp_client.py
         ↓
7. Run the interactive client and experiment
   uv run python client/mcp_client.py

uv run python examples/01_without_mcp.py

uv run python examples/01_without_mcp.py "What is 15 squared plus sqrt(81)?"

uv run python examples/02_with_mcp.py

uv run python examples/02_with_mcp.py "What is 15 squared plus sqrt(81)?"

# Interactive mode — ask Claude anything
uv run python client/mcp_client.py

# Pass a question directly
uv run python client/mcp_client.py "What is the area of a circle with radius 5?"

# Scripted demo — automatically shows all 7 tools
uv run python client/mcp_client.py --demo

# Calculator
"What is log base 2 of 1024, and what is 15 factorial?"

# Weather
"Compare the weather in Tokyo, Mumbai, and New York."

# Notes — try these in sequence
"Save a note called 'mcp-insight' with this text: MCP lets you build tools once and reuse them with any AI."
"What notes do I have saved?"
"Read the note called 'mcp-insight'"

# Word count
"How many words are in: Four score and seven years ago our fathers brought forth on this continent a new nation."

# Date / Time
"What day of the week is it today, and what is the Unix timestamp right now?"

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types

app = Server("my-server")

# Handler 1: Tell clients what tools exist
@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="my_tool",
            description="Does something useful",  # Claude reads this to decide when to use the tool
            inputSchema={"type": "object", "properties": {...}}
        )
    ]

# Handler 2: Execute a tool when called
@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "my_tool":
        result = do_something(arguments)
        return [types.TextContent(type="text", text=result)]

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# 1. Define how to launch the server
server_params = StdioServerParameters(command="python", args=["server/mcp_server.py"])

# 2. Connect
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()                    # MCP handshake

        tools = await session.list_tools()            # discover tools dynamically
        result = await session.call_tool(name, args)  # execute a tool in the server

types.Tool(
    name="calculate",
    description="Evaluate a math expression",   # ← Claude reads this to decide WHEN to use the tool
    inputSchema={
        "type": "object",
        "properties": {
            "expression": {
                "type": "string",
                "description": "e.g. 'sqrt(144)', '2 + 2 * 10'"  # ← Claude reads this to format its call
            }
        },
        "required": ["expression"]
    }
)

Turn 1  →  User: "What is sqrt(144)?"
Turn 2  →  Claude: tool_use { name: "calculate", input: { "expression": "sqrt(144)" } }
Turn 3  →  User:   tool_result { content: "Result: 12.0" }
Turn 4  →  Claude: "The square root of 144 is 12."   [stop_reason: "end_turn"]

# ❌ Tool schemas defined HERE (in the AI client)
TOOLS = [{"name": "calculate", "description": "...", "input_schema": {...}}]

# ❌ Tool logic runs HERE (in the AI client)
def execute_tool_locally(name, args):
    if name == "calculate":
        return str(eval(args["expression"], ...))

# ❌ Reuse = copy-paste this entire file into every new app

# ✅ Tool schemas come FROM the server (zero hardcoding here)
tools_response = await session.list_tools()
anthropic_tools = [{"name": t.name, ...} for t in tools_response.tools]

# ✅ Tool logic runs IN the server (zero implementation code here)
result = await session.call_tool(block.name, block.input)

# ✅ Reuse = point any new app at the same server

load_dotenv(Path(__file__).parent.parent / ".env", override=True)

# Does the .env file exist and contain the key?
cat .env | grep ANTHROPIC_API_KEY

# Does it load correctly?
uv run python -c "
from dotenv import load_dotenv; import os
load_dotenv('.env', override=True)
key = os.environ.get('ANTHROPIC_API_KEY', '')
print('OK' if key.startswith('sk-ant') else 'Missing or wrong format')
"

anthropic.BadRequestError: Your credit balance is too low to access the Anthropic API.

uv run python examples/01_without_mcp.py    # ✓ uses venv
python examples/01_without_mcp.py           # ✗ uses system Python

source .venv/bin/activate
python examples/01_without_mcp.py

uv run python client/mcp_client.py    # ✓ the client launches the server automatically