MCP

Select frameworks to compare

Pick one or more frameworks from the bar above

MCP

OpenAI

# MCP server — a company employee directory exposed as tools.
#
# This server is not framework-specific. It uses the standard MCP Python SDK
# (pip install mcp). Any MCP-compatible agent can connect, discover these tools,
# and call them — without needing this source code.
#
# Compare with the Tools section where tools lived inside the agent's file.
# Here they live on a separate server that ships, deploys, and scales independently.

from mcp.server.fastmcp import FastMCP
import json

mcp = FastMCP("Company Directory")

# --- Mock data ---

# Department rosters — summary data for browsing
# In production: query from HR database or org-chart API
DEPARTMENTS = {
    "engineering": [
        {"id": "E001", "name": "Alice Chen", "role": "Engineering Manager"},
        {"id": "E002", "name": "Bob Smith", "role": "Senior Developer"},
        {"id": "E003", "name": "Carol Wu", "role": "Developer"},
    ],
    "sales": [
        {"id": "E004", "name": "Diana Ross", "role": "Sales Director"},
        {"id": "E005", "name": "Ethan Kim", "role": "Account Executive"},
    ],
    "design": [
        {"id": "E006", "name": "Frank Lee", "role": "Design Lead"},
    ],
}

# Employee profiles — full records keyed by employee ID
# In production: query from directory service (LDAP, Workday, etc.)
PROFILES = {
    "E001": {"name": "Alice Chen", "email": "alice@company.com", "department": "engineering", "role": "Engineering Manager", "office": "SF-4A"},
    "E002": {"name": "Bob Smith", "email": "bob@company.com", "department": "engineering", "role": "Senior Developer", "office": "SF-4B"},
    "E003": {"name": "Carol Wu", "email": "carol@company.com", "department": "engineering", "role": "Developer", "office": "SF-4C"},
    "E004": {"name": "Diana Ross", "email": "diana@company.com", "department": "sales", "role": "Sales Director", "office": "NY-12A"},
    "E005": {"name": "Ethan Kim", "email": "ethan@company.com", "department": "sales", "role": "Account Executive", "office": "NY-12B"},
    "E006": {"name": "Frank Lee", "email": "frank@company.com", "department": "design", "role": "Design Lead", "office": "SF-5A"},
}


# --- Tools ---
# MCP tools are functions decorated with @mcp.tool(). The SDK extracts
# the function name, docstring, and type hints to build the tool schema
# that clients discover at runtime.

@mcp.tool()
def list_employees(department: str) -> str:
    """List employees in a department. Returns employee IDs, names, and roles."""
    employees = DEPARTMENTS.get(department.lower())
    if not employees:
        available = ", ".join(DEPARTMENTS.keys())
        return f"Unknown department '{department}'. Available: {available}"
    return json.dumps(employees, indent=2)

@mcp.tool()
def get_employee(employee_id: str) -> str:
    """Get full profile for an employee by ID. Returns name, email, department, role, and office."""
    profile = PROFILES.get(employee_id.upper())
    if not profile:
        return f"No employee with ID '{employee_id}'."
    return json.dumps(profile, indent=2)


# stdio transport — the client starts this server as a subprocess.
# stdin/stdout carry the MCP protocol messages (JSON-RPC).
mcp.run()

# MCP client — OpenAI with standard MCP Python client.
#
# OpenAI's Responses API has built-in MCP support (type: "mcp"), but it
# requires a publicly-reachable server URL — OpenAI's servers connect to
# yours. For local/stdio transport we use the standard MCP client instead:
# discover tools, convert schemas to OpenAI format, and run the tool loop.
#
# The client starts the MCP server as a subprocess (stdio transport).

import asyncio
import json
from openai import AsyncOpenAI
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

LLM_MODEL = "gpt-5.4"

client = AsyncOpenAI()

server = StdioServerParameters(command="uv", args=["run", "server.py"])


async def main():
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Discover tools from the MCP server and convert to OpenAI format.
            # MCP tool schemas are JSON Schema — same format OpenAI expects.
            mcp_tools = await session.list_tools()
            tools = [
                {
                    "type": "function",
                    "function": {
                        "name": t.name,
                        "description": t.description or "",
                        "parameters": t.inputSchema,
                    },
                }
                for t in mcp_tools.tools
            ]

            messages = [
                {"role": "user", "content": "Who's the engineering manager and what's their email?"}
            ]

            # Agentic loop — keep calling the LLM until it stops requesting tools.
            while True:
                response = await client.chat.completions.create(
                    model=LLM_MODEL, messages=messages, tools=tools,
                )
                choice = response.choices[0]

                if choice.finish_reason == "tool_calls":
                    messages.append(choice.message)
                    for tc in choice.message.tool_calls:
                        result = await session.call_tool(
                            tc.function.name, json.loads(tc.function.arguments),
                        )
                        messages.append({
                            "role": "tool",
                            "tool_call_id": tc.id,
                            "content": result.content[0].text,
                        })
                else:
                    print(choice.message.content)
                    break


asyncio.run(main())
# -> list_employees("engineering")   -> Alice Chen (E001), Bob Smith, Carol Wu
# -> get_employee("E001")            -> alice@company.com
# "The engineering manager is Alice Chen. Her email is alice@company.com."

MCP: Tools on a server, not in the agent
=========================================

Before (e.g. the Tools section):

  Agent process
  ├── tools = [get_weather, ...]   ← defined here
  └── agent.run("question")        ← called here


After (MCP):

  Agent (client.py)              MCP Server (server.py)
  ┌──────────────┐   stdio/http   ┌──────────────────┐
  │              │◄──────────────►│                  │
  │  tools = ?   │   1. connect   │  list_employees  │
  │              │───────────────►│  get_employee    │
  │              │   2. discover  │                  │
  │              │◄───────────────│  (tool schemas)  │
  │              │                │                  │
  │  LLM call ───┼── 3. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  LLM call ───┼── 4. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  response    │   5. done      │                  │
  └──────────────┘                └──────────────────┘

Why this matters:
• Server ships independently — no agent redeploy when tools change
• One server serves many agents — any MCP client can connect
• Agent discovers tools at runtime — no hardcoded tool list
• Tools can live behind auth, in different languages, on different machines

Anthropic

# MCP server — a company employee directory exposed as tools.
#
# This server is not framework-specific. It uses the standard MCP Python SDK
# (pip install mcp). Any MCP-compatible agent can connect, discover these tools,
# and call them — without needing this source code.
#
# Compare with the Tools section where tools lived inside the agent's file.
# Here they live on a separate server that ships, deploys, and scales independently.

from mcp.server.fastmcp import FastMCP
import json

mcp = FastMCP("Company Directory")

# --- Mock data ---

# Department rosters — summary data for browsing
# In production: query from HR database or org-chart API
DEPARTMENTS = {
    "engineering": [
        {"id": "E001", "name": "Alice Chen", "role": "Engineering Manager"},
        {"id": "E002", "name": "Bob Smith", "role": "Senior Developer"},
        {"id": "E003", "name": "Carol Wu", "role": "Developer"},
    ],
    "sales": [
        {"id": "E004", "name": "Diana Ross", "role": "Sales Director"},
        {"id": "E005", "name": "Ethan Kim", "role": "Account Executive"},
    ],
    "design": [
        {"id": "E006", "name": "Frank Lee", "role": "Design Lead"},
    ],
}

# Employee profiles — full records keyed by employee ID
# In production: query from directory service (LDAP, Workday, etc.)
PROFILES = {
    "E001": {"name": "Alice Chen", "email": "alice@company.com", "department": "engineering", "role": "Engineering Manager", "office": "SF-4A"},
    "E002": {"name": "Bob Smith", "email": "bob@company.com", "department": "engineering", "role": "Senior Developer", "office": "SF-4B"},
    "E003": {"name": "Carol Wu", "email": "carol@company.com", "department": "engineering", "role": "Developer", "office": "SF-4C"},
    "E004": {"name": "Diana Ross", "email": "diana@company.com", "department": "sales", "role": "Sales Director", "office": "NY-12A"},
    "E005": {"name": "Ethan Kim", "email": "ethan@company.com", "department": "sales", "role": "Account Executive", "office": "NY-12B"},
    "E006": {"name": "Frank Lee", "email": "frank@company.com", "department": "design", "role": "Design Lead", "office": "SF-5A"},
}


# --- Tools ---
# MCP tools are functions decorated with @mcp.tool(). The SDK extracts
# the function name, docstring, and type hints to build the tool schema
# that clients discover at runtime.

@mcp.tool()
def list_employees(department: str) -> str:
    """List employees in a department. Returns employee IDs, names, and roles."""
    employees = DEPARTMENTS.get(department.lower())
    if not employees:
        available = ", ".join(DEPARTMENTS.keys())
        return f"Unknown department '{department}'. Available: {available}"
    return json.dumps(employees, indent=2)

@mcp.tool()
def get_employee(employee_id: str) -> str:
    """Get full profile for an employee by ID. Returns name, email, department, role, and office."""
    profile = PROFILES.get(employee_id.upper())
    if not profile:
        return f"No employee with ID '{employee_id}'."
    return json.dumps(profile, indent=2)


# stdio transport — the client starts this server as a subprocess.
# stdin/stdout carry the MCP protocol messages (JSON-RPC).
mcp.run()

# MCP client — Anthropic with standard MCP Python client.
#
# Anthropic's Messages API has beta MCP support (mcp_servers param), but it
# requires a publicly-reachable server URL — Anthropic's servers connect to
# yours. For local/stdio transport we use the standard MCP client instead:
# discover tools, convert schemas to Anthropic format, and run the tool loop.
#
# The client starts the MCP server as a subprocess (stdio transport).

import asyncio
import json
import anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

LLM_MODEL = "claude-sonnet-4-20250514"

client = anthropic.AsyncAnthropic()

server = StdioServerParameters(command="uv", args=["run", "server.py"])


async def main():
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Discover tools from the MCP server and convert to Anthropic format.
            # Anthropic uses "input_schema" instead of OpenAI's "parameters".
            mcp_tools = await session.list_tools()
            tools = [
                {
                    "name": t.name,
                    "description": t.description or "",
                    "input_schema": t.inputSchema,
                }
                for t in mcp_tools.tools
            ]

            messages = [
                {"role": "user", "content": "Who's the engineering manager and what's their email?"}
            ]

            # Agentic loop — keep calling the LLM until it stops requesting tools.
            while True:
                response = await client.messages.create(
                    model=LLM_MODEL, max_tokens=1024, messages=messages, tools=tools,
                )

                if response.stop_reason == "tool_use":
                    messages.append({"role": "assistant", "content": response.content})
                    tool_results = []
                    for block in response.content:
                        if block.type == "tool_use":
                            result = await session.call_tool(block.name, block.input)
                            tool_results.append({
                                "type": "tool_result",
                                "tool_use_id": block.id,
                                "content": result.content[0].text,
                            })
                    messages.append({"role": "user", "content": tool_results})
                else:
                    print(response.content[-1].text)
                    break


asyncio.run(main())
# -> list_employees("engineering")   -> Alice Chen (E001), Bob Smith, Carol Wu
# -> get_employee("E001")            -> alice@company.com
# "The engineering manager is Alice Chen. Her email is alice@company.com."

MCP: Tools on a server, not in the agent
=========================================

Before (e.g. the Tools section):

  Agent process
  ├── tools = [get_weather, ...]   ← defined here
  └── agent.run("question")        ← called here


After (MCP):

  Agent (client.py)              MCP Server (server.py)
  ┌──────────────┐   stdio/http   ┌──────────────────┐
  │              │◄──────────────►│                  │
  │  tools = ?   │   1. connect   │  list_employees  │
  │              │───────────────►│  get_employee    │
  │              │   2. discover  │                  │
  │              │◄───────────────│  (tool schemas)  │
  │              │                │                  │
  │  LLM call ───┼── 3. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  LLM call ───┼── 4. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  response    │   5. done      │                  │
  └──────────────┘                └──────────────────┘

Why this matters:
• Server ships independently — no agent redeploy when tools change
• One server serves many agents — any MCP client can connect
• Agent discovers tools at runtime — no hardcoded tool list
• Tools can live behind auth, in different languages, on different machines

Gemini

# MCP server — a company employee directory exposed as tools.
#
# This server is not framework-specific. It uses the standard MCP Python SDK
# (pip install mcp). Any MCP-compatible agent can connect, discover these tools,
# and call them — without needing this source code.
#
# Compare with the Tools section where tools lived inside the agent's file.
# Here they live on a separate server that ships, deploys, and scales independently.

from mcp.server.fastmcp import FastMCP
import json

mcp = FastMCP("Company Directory")

# --- Mock data ---

# Department rosters — summary data for browsing
# In production: query from HR database or org-chart API
DEPARTMENTS = {
    "engineering": [
        {"id": "E001", "name": "Alice Chen", "role": "Engineering Manager"},
        {"id": "E002", "name": "Bob Smith", "role": "Senior Developer"},
        {"id": "E003", "name": "Carol Wu", "role": "Developer"},
    ],
    "sales": [
        {"id": "E004", "name": "Diana Ross", "role": "Sales Director"},
        {"id": "E005", "name": "Ethan Kim", "role": "Account Executive"},
    ],
    "design": [
        {"id": "E006", "name": "Frank Lee", "role": "Design Lead"},
    ],
}

# Employee profiles — full records keyed by employee ID
# In production: query from directory service (LDAP, Workday, etc.)
PROFILES = {
    "E001": {"name": "Alice Chen", "email": "alice@company.com", "department": "engineering", "role": "Engineering Manager", "office": "SF-4A"},
    "E002": {"name": "Bob Smith", "email": "bob@company.com", "department": "engineering", "role": "Senior Developer", "office": "SF-4B"},
    "E003": {"name": "Carol Wu", "email": "carol@company.com", "department": "engineering", "role": "Developer", "office": "SF-4C"},
    "E004": {"name": "Diana Ross", "email": "diana@company.com", "department": "sales", "role": "Sales Director", "office": "NY-12A"},
    "E005": {"name": "Ethan Kim", "email": "ethan@company.com", "department": "sales", "role": "Account Executive", "office": "NY-12B"},
    "E006": {"name": "Frank Lee", "email": "frank@company.com", "department": "design", "role": "Design Lead", "office": "SF-5A"},
}


# --- Tools ---
# MCP tools are functions decorated with @mcp.tool(). The SDK extracts
# the function name, docstring, and type hints to build the tool schema
# that clients discover at runtime.

@mcp.tool()
def list_employees(department: str) -> str:
    """List employees in a department. Returns employee IDs, names, and roles."""
    employees = DEPARTMENTS.get(department.lower())
    if not employees:
        available = ", ".join(DEPARTMENTS.keys())
        return f"Unknown department '{department}'. Available: {available}"
    return json.dumps(employees, indent=2)

@mcp.tool()
def get_employee(employee_id: str) -> str:
    """Get full profile for an employee by ID. Returns name, email, department, role, and office."""
    profile = PROFILES.get(employee_id.upper())
    if not profile:
        return f"No employee with ID '{employee_id}'."
    return json.dumps(profile, indent=2)


# stdio transport — the client starts this server as a subprocess.
# stdin/stdout carry the MCP protocol messages (JSON-RPC).
mcp.run()

# MCP client — Gemini with MCP session passed directly as a tool.
#
# Gemini's unique approach: pass the MCP ClientSession directly as a tool.
# The SDK extracts tool schemas and handles calling internally.
# No manual conversion needed.
#
# The client starts the MCP server as a subprocess (stdio transport).

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai

LLM_MODEL = "gemini-2.5-flash"

# stdio_client manages the MCP subprocess. ClientSession handles the JSON-RPC
# protocol. The session is passed directly to Gemini as a tool — the SDK
# discovers tool schemas and handles calling automatically.
# Compare with the Tools section where tools were plain Python functions.

server = StdioServerParameters(command="uv", args=["run", "server.py"])

client = genai.Client()

async def main():
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            response = await client.aio.models.generate_content(
                model=LLM_MODEL,
                contents="Who's the engineering manager and what's their email?",
                config=genai.types.GenerateContentConfig(
                    tools=[session],
                ),
            )
            print(response.text)

asyncio.run(main())
# -> list_employees("engineering")   → Alice Chen (E001), Bob Smith, Carol Wu
# -> get_employee("E001")            → alice@company.com
# "The engineering manager is Alice Chen. Her email is alice@company.com."

MCP: Tools on a server, not in the agent
=========================================

Before (e.g. the Tools section):

  Agent process
  ├── tools = [get_weather, ...]   ← defined here
  └── agent.run("question")        ← called here


After (MCP):

  Agent (client.py)              MCP Server (server.py)
  ┌──────────────┐   stdio/http   ┌──────────────────┐
  │              │◄──────────────►│                  │
  │  tools = ?   │   1. connect   │  list_employees  │
  │              │───────────────►│  get_employee    │
  │              │   2. discover  │                  │
  │              │◄───────────────│  (tool schemas)  │
  │              │                │                  │
  │  LLM call ───┼── 3. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  LLM call ───┼── 4. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  response    │   5. done      │                  │
  └──────────────┘                └──────────────────┘

Why this matters:
• Server ships independently — no agent redeploy when tools change
• One server serves many agents — any MCP client can connect
• Agent discovers tools at runtime — no hardcoded tool list
• Tools can live behind auth, in different languages, on different machines

Pydantic AI

# MCP server — a company employee directory exposed as tools.
#
# This server is not framework-specific. It uses the standard MCP Python SDK
# (pip install mcp). Any MCP-compatible agent can connect, discover these tools,
# and call them — without needing this source code.
#
# Compare with the Tools section where tools lived inside the agent's file.
# Here they live on a separate server that ships, deploys, and scales independently.

from mcp.server.fastmcp import FastMCP
import json

mcp = FastMCP("Company Directory")

# --- Mock data ---

# Department rosters — summary data for browsing
# In production: query from HR database or org-chart API
DEPARTMENTS = {
    "engineering": [
        {"id": "E001", "name": "Alice Chen", "role": "Engineering Manager"},
        {"id": "E002", "name": "Bob Smith", "role": "Senior Developer"},
        {"id": "E003", "name": "Carol Wu", "role": "Developer"},
    ],
    "sales": [
        {"id": "E004", "name": "Diana Ross", "role": "Sales Director"},
        {"id": "E005", "name": "Ethan Kim", "role": "Account Executive"},
    ],
    "design": [
        {"id": "E006", "name": "Frank Lee", "role": "Design Lead"},
    ],
}

# Employee profiles — full records keyed by employee ID
# In production: query from directory service (LDAP, Workday, etc.)
PROFILES = {
    "E001": {"name": "Alice Chen", "email": "alice@company.com", "department": "engineering", "role": "Engineering Manager", "office": "SF-4A"},
    "E002": {"name": "Bob Smith", "email": "bob@company.com", "department": "engineering", "role": "Senior Developer", "office": "SF-4B"},
    "E003": {"name": "Carol Wu", "email": "carol@company.com", "department": "engineering", "role": "Developer", "office": "SF-4C"},
    "E004": {"name": "Diana Ross", "email": "diana@company.com", "department": "sales", "role": "Sales Director", "office": "NY-12A"},
    "E005": {"name": "Ethan Kim", "email": "ethan@company.com", "department": "sales", "role": "Account Executive", "office": "NY-12B"},
    "E006": {"name": "Frank Lee", "email": "frank@company.com", "department": "design", "role": "Design Lead", "office": "SF-5A"},
}


# --- Tools ---
# MCP tools are functions decorated with @mcp.tool(). The SDK extracts
# the function name, docstring, and type hints to build the tool schema
# that clients discover at runtime.

@mcp.tool()
def list_employees(department: str) -> str:
    """List employees in a department. Returns employee IDs, names, and roles."""
    employees = DEPARTMENTS.get(department.lower())
    if not employees:
        available = ", ".join(DEPARTMENTS.keys())
        return f"Unknown department '{department}'. Available: {available}"
    return json.dumps(employees, indent=2)

@mcp.tool()
def get_employee(employee_id: str) -> str:
    """Get full profile for an employee by ID. Returns name, email, department, role, and office."""
    profile = PROFILES.get(employee_id.upper())
    if not profile:
        return f"No employee with ID '{employee_id}'."
    return json.dumps(profile, indent=2)


# stdio transport — the client starts this server as a subprocess.
# stdin/stdout carry the MCP protocol messages (JSON-RPC).
mcp.run()

# MCP client — Pydantic AI with first-class MCP support.
#
# Pydantic AI has first-class MCP support. The agent discovers tools when
# the MCP server subprocess starts. No manual tool conversion, no explicit
# session management.
#
# The client starts the MCP server as a subprocess (stdio transport).

import asyncio
from pydantic_ai import Agent
from pydantic_ai.mcp import MCPServerStdio

LLM_MODEL = "openai:gpt-5.4"

# MCPServerStdio wraps a subprocess. Pass it to toolsets — the agent
# discovers available tools at runtime via the MCP protocol.
# Compare with the Tools section where tools were @agent.tool functions.

server = MCPServerStdio("uv", args=["run", "server.py"])

agent = Agent(LLM_MODEL, toolsets=[server])

async def main():
    async with agent:
        result = await agent.run(
            "Who's the engineering manager and what's their email?",
        )
        print(result.output)

asyncio.run(main())
# -> list_employees("engineering")   → Alice Chen (E001), Bob Smith, Carol Wu
# -> get_employee("E001")            → alice@company.com
# "The engineering manager is Alice Chen. Her email is alice@company.com."

MCP: Tools on a server, not in the agent
=========================================

Before (e.g. the Tools section):

  Agent process
  ├── tools = [get_weather, ...]   ← defined here
  └── agent.run("question")        ← called here


After (MCP):

  Agent (client.py)              MCP Server (server.py)
  ┌──────────────┐   stdio/http   ┌──────────────────┐
  │              │◄──────────────►│                  │
  │  tools = ?   │   1. connect   │  list_employees  │
  │              │───────────────►│  get_employee    │
  │              │   2. discover  │                  │
  │              │◄───────────────│  (tool schemas)  │
  │              │                │                  │
  │  LLM call ───┼── 3. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  LLM call ───┼── 4. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  response    │   5. done      │                  │
  └──────────────┘                └──────────────────┘

Why this matters:
• Server ships independently — no agent redeploy when tools change
• One server serves many agents — any MCP client can connect
• Agent discovers tools at runtime — no hardcoded tool list
• Tools can live behind auth, in different languages, on different machines

LangGraph

# MCP server — a company employee directory exposed as tools.
#
# This server is not framework-specific. It uses the standard MCP Python SDK
# (pip install mcp). Any MCP-compatible agent can connect, discover these tools,
# and call them — without needing this source code.
#
# Compare with the Tools section where tools lived inside the agent's file.
# Here they live on a separate server that ships, deploys, and scales independently.

from mcp.server.fastmcp import FastMCP
import json

mcp = FastMCP("Company Directory")

# --- Mock data ---

# Department rosters — summary data for browsing
# In production: query from HR database or org-chart API
DEPARTMENTS = {
    "engineering": [
        {"id": "E001", "name": "Alice Chen", "role": "Engineering Manager"},
        {"id": "E002", "name": "Bob Smith", "role": "Senior Developer"},
        {"id": "E003", "name": "Carol Wu", "role": "Developer"},
    ],
    "sales": [
        {"id": "E004", "name": "Diana Ross", "role": "Sales Director"},
        {"id": "E005", "name": "Ethan Kim", "role": "Account Executive"},
    ],
    "design": [
        {"id": "E006", "name": "Frank Lee", "role": "Design Lead"},
    ],
}

# Employee profiles — full records keyed by employee ID
# In production: query from directory service (LDAP, Workday, etc.)
PROFILES = {
    "E001": {"name": "Alice Chen", "email": "alice@company.com", "department": "engineering", "role": "Engineering Manager", "office": "SF-4A"},
    "E002": {"name": "Bob Smith", "email": "bob@company.com", "department": "engineering", "role": "Senior Developer", "office": "SF-4B"},
    "E003": {"name": "Carol Wu", "email": "carol@company.com", "department": "engineering", "role": "Developer", "office": "SF-4C"},
    "E004": {"name": "Diana Ross", "email": "diana@company.com", "department": "sales", "role": "Sales Director", "office": "NY-12A"},
    "E005": {"name": "Ethan Kim", "email": "ethan@company.com", "department": "sales", "role": "Account Executive", "office": "NY-12B"},
    "E006": {"name": "Frank Lee", "email": "frank@company.com", "department": "design", "role": "Design Lead", "office": "SF-5A"},
}


# --- Tools ---
# MCP tools are functions decorated with @mcp.tool(). The SDK extracts
# the function name, docstring, and type hints to build the tool schema
# that clients discover at runtime.

@mcp.tool()
def list_employees(department: str) -> str:
    """List employees in a department. Returns employee IDs, names, and roles."""
    employees = DEPARTMENTS.get(department.lower())
    if not employees:
        available = ", ".join(DEPARTMENTS.keys())
        return f"Unknown department '{department}'. Available: {available}"
    return json.dumps(employees, indent=2)

@mcp.tool()
def get_employee(employee_id: str) -> str:
    """Get full profile for an employee by ID. Returns name, email, department, role, and office."""
    profile = PROFILES.get(employee_id.upper())
    if not profile:
        return f"No employee with ID '{employee_id}'."
    return json.dumps(profile, indent=2)


# stdio transport — the client starts this server as a subprocess.
# stdin/stdout carry the MCP protocol messages (JSON-RPC).
mcp.run()

# MCP client — LangGraph with langchain-mcp-adapters.
#
# LangGraph uses langchain-mcp-adapters to bridge MCP and LangChain.
# load_mcp_tools() converts MCP tool schemas into LangChain BaseTool
# objects — after that, the agent works exactly like any other LangGraph agent.
#
# The client starts the MCP server as a subprocess (stdio transport).

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from langchain_mcp_adapters.tools import load_mcp_tools
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

LLM_MODEL = "gpt-5.4"

# StdioServerParameters configures the subprocess — same MCP server,
# but launched as a child process instead of over HTTP.
# stdio_client handles the JSON-RPC protocol over stdin/stdout.

server = StdioServerParameters(command="uv", args=["run", "server.py"])

async def main():
    async with stdio_client(server) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Convert MCP tools into LangChain tools. From here on,
            # the agent doesn't know or care they came from MCP.
            tools = await load_mcp_tools(session)

            agent = create_agent(ChatOpenAI(model=LLM_MODEL), tools)
            result = await agent.ainvoke({
                "messages": "Who's the engineering manager and what's their email?",
            })
            print(result["messages"][-1].content)

asyncio.run(main())
# -> list_employees("engineering")   → Alice Chen (E001), Bob Smith, Carol Wu
# -> get_employee("E001")            → alice@company.com
# "The engineering manager is Alice Chen. Her email is alice@company.com."

MCP: Tools on a server, not in the agent
=========================================

Before (e.g. the Tools section):

  Agent process
  ├── tools = [get_weather, ...]   ← defined here
  └── agent.run("question")        ← called here


After (MCP):

  Agent (client.py)              MCP Server (server.py)
  ┌──────────────┐   stdio/http   ┌──────────────────┐
  │              │◄──────────────►│                  │
  │  tools = ?   │   1. connect   │  list_employees  │
  │              │───────────────►│  get_employee    │
  │              │   2. discover  │                  │
  │              │◄───────────────│  (tool schemas)  │
  │              │                │                  │
  │  LLM call ───┼── 3. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  LLM call ───┼── 4. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  response    │   5. done      │                  │
  └──────────────┘                └──────────────────┘

Why this matters:
• Server ships independently — no agent redeploy when tools change
• One server serves many agents — any MCP client can connect
• Agent discovers tools at runtime — no hardcoded tool list
• Tools can live behind auth, in different languages, on different machines

AI SDK

// MCP server — a company employee directory exposed as tools.
//
// This server is not framework-specific. It uses the standard MCP TypeScript SDK
// (@modelcontextprotocol/sdk). Any MCP-compatible agent can connect, discover
// these tools, and call them — without needing this source code.
//
// Compare with the Tools section where tools lived inside the agent's file.
// Here they live on a separate server that ships, deploys, and scales independently.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// --- Mock data ---

// Department rosters — summary data for browsing
// In production: query from HR database or org-chart API
const DEPARTMENTS: Record<string, { id: string; name: string; role: string }[]> = {
  engineering: [
    { id: "E001", name: "Alice Chen", role: "Engineering Manager" },
    { id: "E002", name: "Bob Smith", role: "Senior Developer" },
    { id: "E003", name: "Carol Wu", role: "Developer" },
  ],
  sales: [
    { id: "E004", name: "Diana Ross", role: "Sales Director" },
    { id: "E005", name: "Ethan Kim", role: "Account Executive" },
  ],
  design: [
    { id: "E006", name: "Frank Lee", role: "Design Lead" },
  ],
};

// Employee profiles — full records keyed by employee ID
// In production: query from directory service (LDAP, Workday, etc.)
const PROFILES: Record<string, { name: string; email: string; department: string; role: string; office: string }> = {
  E001: { name: "Alice Chen", email: "alice@company.com", department: "engineering", role: "Engineering Manager", office: "SF-4A" },
  E002: { name: "Bob Smith", email: "bob@company.com", department: "engineering", role: "Senior Developer", office: "SF-4B" },
  E003: { name: "Carol Wu", email: "carol@company.com", department: "engineering", role: "Developer", office: "SF-4C" },
  E004: { name: "Diana Ross", email: "diana@company.com", department: "sales", role: "Sales Director", office: "NY-12A" },
  E005: { name: "Ethan Kim", email: "ethan@company.com", department: "sales", role: "Account Executive", office: "NY-12B" },
  E006: { name: "Frank Lee", email: "frank@company.com", department: "design", role: "Design Lead", office: "SF-5A" },
};


// --- Server + Tools ---
// McpServer registers tools with typed Zod schemas. The SDK handles
// JSON-RPC protocol, tool discovery, and schema validation automatically.

const server = new McpServer({ name: "Company Directory", version: "1.0.0" });

server.tool(
  "list_employees",
  "List employees in a department. Returns employee IDs, names, and roles.",
  { department: z.string() },
  async ({ department }) => {
    const employees = DEPARTMENTS[department.toLowerCase()];
    if (!employees) {
      const available = Object.keys(DEPARTMENTS).join(", ");
      return { content: [{ type: "text", text: `Unknown department '${department}'. Available: ${available}` }] };
    }
    return { content: [{ type: "text", text: JSON.stringify(employees, null, 2) }] };
  },
);

server.tool(
  "get_employee",
  "Get full profile for an employee by ID. Returns name, email, department, role, and office.",
  { employee_id: z.string() },
  async ({ employee_id }) => {
    const profile = PROFILES[employee_id.toUpperCase()];
    if (!profile) {
      return { content: [{ type: "text", text: `No employee with ID '${employee_id}'.` }] };
    }
    return { content: [{ type: "text", text: JSON.stringify(profile, null, 2) }] };
  },
);


// stdio transport — the client starts this server as a subprocess.
// stdin/stdout carry the MCP protocol messages (JSON-RPC).
const transport = new StdioServerTransport();
await server.connect(transport);

// MCP client — AI SDK with @ai-sdk/mcp.
//
// The @ai-sdk/mcp package bridges MCP and the AI SDK. client.tools()
// converts MCP tool schemas into AI SDK tool objects, which plug
// directly into generateText().
//
// The client starts the MCP server as a subprocess (stdio transport).

import { createMCPClient } from "@ai-sdk/mcp";
import { Experimental_StdioMCPTransport as StdioTransport } from "@ai-sdk/mcp/mcp-stdio";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";

const LLM_MODEL = "gpt-5.4";

// createMCPClient connects to the server, discovers tools, and returns
// an object whose .tools() method produces AI SDK-compatible tool objects.
// Compare with the Tools section where tools were defined inline with zod schemas.

const client = await createMCPClient({
  transport: new StdioTransport({
    command: "bun",
    args: ["run", "server.ts"],
  }),
});

const result = await generateText({
  model: openai(LLM_MODEL),
  prompt: "Who's the engineering manager and what's their email?",
  tools: await client.tools(),
  stopWhen: stepCountIs(5),
});

console.log(result.text);
await client.close();
// -> list_employees("engineering")   → Alice Chen (E001), Bob Smith, Carol Wu
// -> get_employee("E001")            → alice@company.com
// "The engineering manager is Alice Chen. Her email is alice@company.com."

MCP: Tools on a server, not in the agent
=========================================

Before (e.g. the Tools section):

  Agent process
  ├── tools = [get_weather, ...]   ← defined here
  └── agent.run("question")        ← called here


After (MCP):

  Agent (client.py)              MCP Server (server.py)
  ┌──────────────┐   stdio/http   ┌──────────────────┐
  │              │◄──────────────►│                  │
  │  tools = ?   │   1. connect   │  list_employees  │
  │              │───────────────►│  get_employee    │
  │              │   2. discover  │                  │
  │              │◄───────────────│  (tool schemas)  │
  │              │                │                  │
  │  LLM call ───┼── 3. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  LLM call ───┼── 4. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  response    │   5. done      │                  │
  └──────────────┘                └──────────────────┘

Why this matters:
• Server ships independently — no agent redeploy when tools change
• One server serves many agents — any MCP client can connect
• Agent discovers tools at runtime — no hardcoded tool list
• Tools can live behind auth, in different languages, on different machines

Mastra

// MCP server — a company employee directory exposed as tools.
//
// This server uses the standard MCP TypeScript SDK (@modelcontextprotocol/sdk).
// Any MCP-compatible agent can connect, discover these tools, and call them.
//
// Compare with the Tools section where tools lived inside the agent's file.
// Here they live on a separate server that ships, deploys, and scales independently.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// --- Mock data ---

// Department rosters — summary data for browsing
// In production: query from HR database or org-chart API
const DEPARTMENTS: Record<string, { id: string; name: string; role: string }[]> = {
  engineering: [
    { id: "E001", name: "Alice Chen", role: "Engineering Manager" },
    { id: "E002", name: "Bob Smith", role: "Senior Developer" },
    { id: "E003", name: "Carol Wu", role: "Developer" },
  ],
  sales: [
    { id: "E004", name: "Diana Ross", role: "Sales Director" },
    { id: "E005", name: "Ethan Kim", role: "Account Executive" },
  ],
  design: [
    { id: "E006", name: "Frank Lee", role: "Design Lead" },
  ],
};

// Employee profiles — full records keyed by employee ID
// In production: query from directory service (LDAP, Workday, etc.)
const PROFILES: Record<string, { name: string; email: string; department: string; role: string; office: string }> = {
  E001: { name: "Alice Chen", email: "alice@company.com", department: "engineering", role: "Engineering Manager", office: "SF-4A" },
  E002: { name: "Bob Smith", email: "bob@company.com", department: "engineering", role: "Senior Developer", office: "SF-4B" },
  E003: { name: "Carol Wu", email: "carol@company.com", department: "engineering", role: "Developer", office: "SF-4C" },
  E004: { name: "Diana Ross", email: "diana@company.com", department: "sales", role: "Sales Director", office: "NY-12A" },
  E005: { name: "Ethan Kim", email: "ethan@company.com", department: "sales", role: "Account Executive", office: "NY-12B" },
  E006: { name: "Frank Lee", email: "frank@company.com", department: "design", role: "Design Lead", office: "SF-5A" },
};


// --- Server + Tools ---
// McpServer registers tools with typed Zod schemas. The SDK handles
// JSON-RPC protocol, tool discovery, and schema validation automatically.

const server = new McpServer({ name: "Company Directory", version: "1.0.0" });

server.tool(
  "list_employees",
  "List employees in a department. Returns employee IDs, names, and roles.",
  { department: z.string() },
  async ({ department }) => {
    const employees = DEPARTMENTS[department.toLowerCase()];
    if (!employees) {
      const available = Object.keys(DEPARTMENTS).join(", ");
      return { content: [{ type: "text", text: `Unknown department '${department}'. Available: ${available}` }] };
    }
    return { content: [{ type: "text", text: JSON.stringify(employees, null, 2) }] };
  },
);

server.tool(
  "get_employee",
  "Get full profile for an employee by ID. Returns name, email, department, role, and office.",
  { employee_id: z.string() },
  async ({ employee_id }) => {
    const profile = PROFILES[employee_id.toUpperCase()];
    if (!profile) {
      return { content: [{ type: "text", text: `No employee with ID '${employee_id}'.` }] };
    }
    return { content: [{ type: "text", text: JSON.stringify(profile, null, 2) }] };
  },
);


// stdio transport — the client starts this server as a subprocess.
// stdin/stdout carry the MCP protocol messages (JSON-RPC).
const transport = new StdioServerTransport();
await server.connect(transport);

// MCP client — Mastra with @mastra/mcp.
//
// Mastra has full MCP support — both server (see server.ts) and client.
// MCPClient manages the subprocess lifecycle; listTools() returns
// tools ready for any Mastra agent.
//
// The client starts the MCP server as a subprocess (stdio transport).

import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";

const LLM_MODEL = "openai/gpt-5.4";

// MCPClient manages one or more MCP server connections. Each server entry
// specifies how to start the subprocess. listTools() discovers all tools
// across all configured servers.
// Compare with the Tools section where tools were createTool() objects.

const mcp = new MCPClient({
  id: "mcp-client",
  servers: {
    directory: {
      command: "bun",
      args: ["run", "server.ts"],
    },
  },
});

const tools = await mcp.listTools();

const agent = new Agent({
  name: "mcp-agent",
  instructions: "You are a helpful assistant.",
  model: LLM_MODEL,
  tools,
});

const result = await agent.generate(
  "Who's the engineering manager and what's their email?",
  { maxSteps: 5 },
);

console.log(result.text);
await mcp.disconnect();
// -> list_employees("engineering")   → Alice Chen (E001), Bob Smith, Carol Wu
// -> get_employee("E001")            → alice@company.com
// "The engineering manager is Alice Chen. Her email is alice@company.com."

MCP: Tools on a server, not in the agent
=========================================

Before (e.g. the Tools section):

  Agent process
  ├── tools = [get_weather, ...]   ← defined here
  └── agent.run("question")        ← called here


After (MCP):

  Agent (client.py)              MCP Server (server.py)
  ┌──────────────┐   stdio/http   ┌──────────────────┐
  │              │◄──────────────►│                  │
  │  tools = ?   │   1. connect   │  list_employees  │
  │              │───────────────►│  get_employee    │
  │              │   2. discover  │                  │
  │              │◄───────────────│  (tool schemas)  │
  │              │                │                  │
  │  LLM call ───┼── 3. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  LLM call ───┼── 4. call ────►│  execute tool    │
  │              │◄───────────────│  return result   │
  │              │                │                  │
  │  response    │   5. done      │                  │
  └──────────────┘                └──────────────────┘

Why this matters:
• Server ships independently — no agent redeploy when tools change
• One server serves many agents — any MCP client can connect
• Agent discovers tools at runtime — no hardcoded tool list
• Tools can live behind auth, in different languages, on different machines