Lesson 8: MCP — The Universal Tool Protocol

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "sampling": {},
      "roots": { "listChanged": true }
    },
    "clientInfo": {
      "name": "Claude Code",
      "version": "1.0.0"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "tools": {},
      "resources": { "subscribe": true, "listChanged": true }
    },
    "serverInfo": {
      "name": "postgres-mcp",
      "version": "2.1.0"
    }
  }
}

// Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}
 
// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "query",
        "description": "Execute a read-only SQL query against the database",
        "inputSchema": {
          "type": "object",
          "properties": {
            "sql": {
              "type": "string",
              "description": "The SQL SELECT statement to execute"
            }
          },
          "required": ["sql"]
        }
      },
      {
        "name": "list_tables",
        "description": "List all tables in the database",
        "inputSchema": {
          "type": "object",
          "properties": {}
        }
      }
    ]
  }
}

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "query",
    "arguments": {
      "sql": "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 10"
    }
  }
}
 
// Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "id | email                | created_at\n---|----------------------|------------------\n 1 | alice@example.com    | 2026-03-15 09:00\n 2 | bob@example.com      | 2026-03-14 17:30\n..."
      }
    ],
    "isError": false
  }
}

# Test the server runs
npx @modelcontextprotocol/server-postgres --help
 
# Or install globally for faster startup
npm install -g @modelcontextprotocol/server-postgres

# Add postgres MCP server at project scope
claude mcp add --transport stdio \
  --env POSTGRES_CONNECTION_STRING=postgresql://user:pass@localhost:5432/mydb \
  postgres \
  -- npx -y @modelcontextprotocol/server-postgres
 
# Add at user scope (available in all projects)
claude mcp add --scope user --transport stdio \
  --env POSTGRES_CONNECTION_STRING=postgresql://user:pass@localhost:5432/mydb \
  postgres \
  -- npx -y @modelcontextprotocol/server-postgres
 
# List configured servers
claude mcp list
 
# Remove a server
claude mcp remove postgres

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://user:password@localhost:5432/mydb"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/projects",
        "/tmp"
      ]
    }
  }
}

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "POSTGRES_CONNECTION_STRING": "postgresql://readonly_user:pass@localhost:5432/mydb"
      }
    }
  }
}

-- Create a read-only role for Claude
CREATE ROLE claude_readonly;
GRANT CONNECT ON DATABASE mydb TO claude_readonly;
GRANT USAGE ON SCHEMA public TO claude_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claude_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO claude_readonly;
 
-- Create the user
CREATE USER claude_mcp_user WITH PASSWORD 'strong-random-password';
GRANT claude_readonly TO claude_mcp_user;

# Use environment variables — never hardcode credentials in config files
export POSTGRES_CONNECTION_STRING="postgresql://claude_mcp_user:pass@localhost:5432/mydb"
 
# Use .env files with your project (add to .gitignore)
echo "POSTGRES_CONNECTION_STRING=postgresql://..." >> .env
echo ".env" >> .gitignore

# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Create the project
uv init weather-mcp
cd weather-mcp
 
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx
 
# Create the server file
touch weather.py

from typing import Any
 
import httpx
from mcp.server.fastmcp import FastMCP
 
# Initialize FastMCP server — the name appears in Claude's tool list
mcp = FastMCP("weather")
 
# National Weather Service API (US only, no API key needed)
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-mcp/1.0"
 
 
# ============================================================
# Helper functions
# ============================================================
 
async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json",
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None
 
 
def format_alert(feature: dict) -> str:
    """Format an NWS alert into a human-readable string."""
    props = feature["properties"]
    return (
        f"Event: {props.get('event', 'Unknown')}\n"
        f"Area: {props.get('areaDesc', 'Unknown')}\n"
        f"Severity: {props.get('severity', 'Unknown')}\n"
        f"Description: {props.get('description', 'No description available')}\n"
        f"Instructions: {props.get('instruction', 'No specific instructions provided')}"
    )
 
 
# ============================================================
# Tool definitions
# FastMCP reads the type hints and docstring to build the schema
# ============================================================
 
@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get active weather alerts for a US state.
 
    Args:
        state: Two-letter US state code (e.g. CA, NY, TX)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state.upper()}"
    data = await make_nws_request(url)
 
    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."
 
    if not data["features"]:
        return f"No active alerts for {state.upper()}."
 
    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)
 
 
@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """Get a 5-period weather forecast for a specific location.
 
    Args:
        latitude: Latitude of the location (-90 to 90)
        longitude: Longitude of the location (-180 to 180)
    """
    # Step 1: Resolve coordinates to a forecast grid
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)
 
    if not points_data:
        return "Unable to fetch forecast data for this location."
 
    # Step 2: Get the actual forecast from the grid URL
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)
 
    if not forecast_data:
        return "Unable to fetch detailed forecast."
 
    # Step 3: Format the next 5 forecast periods
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:
        forecasts.append(
            f"{period['name']}:\n"
            f"  Temperature: {period['temperature']}°{period['temperatureUnit']}\n"
            f"  Wind: {period['windSpeed']} {period['windDirection']}\n"
            f"  Forecast: {period['detailedForecast']}"
        )
 
    return "\n---\n".join(forecasts)
 
 
# ============================================================
# Entry point
# ============================================================
 
def main():
    # stdio transport: host spawns this process and pipes JSON-RPC
    mcp.run(transport="stdio")
 
 
if __name__ == "__main__":
    main()

# Start the server — it waits for JSON-RPC on stdin
uv run weather.py
 
# In another terminal, use the MCP inspector
npx @modelcontextprotocol/inspector uv run weather.py

# Add to Claude Code (adjust path to your project)
claude mcp add --transport stdio weather \
  -- uv --directory /absolute/path/to/weather-mcp run weather.py
 
# Or add to .mcp.json manually:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/weather-mcp",
        "run",
        "weather.py"
      ]
    }
  }
}

mkdir weather-mcp-ts && cd weather-mcp-ts
npm init -y
npm install @modelcontextprotocol/sdk zod@3
npm install -D @types/node typescript
mkdir src && touch src/index.ts

{
  "type": "module",
  "bin": {
    "weather-mcp": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js",
    "start": "node build/index.js"
  },
  "files": ["build"]
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-mcp/1.0";
 
// Create the MCP server instance
const server = new McpServer({
  name: "weather",
  version: "1.0.0",
});
 
// ============================================================
// Type definitions for NWS API responses
// ============================================================
 
interface AlertFeature {
  properties: {
    event?: string;
    areaDesc?: string;
    severity?: string;
    status?: string;
    headline?: string;
  };
}
 
interface AlertsResponse {
  features: AlertFeature[];
}
 
interface PointsResponse {
  properties: {
    forecast?: string;
  };
}
 
interface ForecastPeriod {
  name?: string;
  temperature?: number;
  temperatureUnit?: string;
  windSpeed?: string;
  windDirection?: string;
  shortForecast?: string;
  detailedForecast?: string;
}
 
interface ForecastResponse {
  properties: {
    periods: ForecastPeriod[];
  };
}
 
// ============================================================
// Helper functions
// ============================================================
 
async function makeNWSRequest<T>(url: string): Promise<T | null> {
  const headers = {
    "User-Agent": USER_AGENT,
    "Accept": "application/geo+json",
  };
  try {
    const response = await fetch(url, { headers });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return (await response.json()) as T;
  } catch (error) {
    // Use stderr — stdout is reserved for JSON-RPC
    console.error("NWS request failed:", error);
    return null;
  }
}
 
function formatAlert(feature: AlertFeature): string {
  const p = feature.properties;
  return [
    `Event: ${p.event ?? "Unknown"}`,
    `Area: ${p.areaDesc ?? "Unknown"}`,
    `Severity: ${p.severity ?? "Unknown"}`,
    `Status: ${p.status ?? "Unknown"}`,
    `Headline: ${p.headline ?? "No headline"}`,
  ].join("\n");
}
 
// ============================================================
// Tool registrations
// ============================================================
 
server.registerTool(
  "get_alerts",
  {
    description: "Get active weather alerts for a US state",
    inputSchema: {
      state: z
        .string()
        .length(2)
        .describe("Two-letter US state code (e.g. CA, NY, TX)"),
    },
  },
  async ({ state }) => {
    const stateCode = state.toUpperCase();
    const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
    const data = await makeNWSRequest<AlertsResponse>(alertsUrl);
 
    if (!data) {
      return {
        content: [{ type: "text", text: "Failed to retrieve alerts data" }],
      };
    }
 
    const features = data.features ?? [];
    if (features.length === 0) {
      return {
        content: [{ type: "text", text: `No active alerts for ${stateCode}` }],
      };
    }
 
    const text = `Active alerts for ${stateCode}:\n\n${features.map(formatAlert).join("\n---\n")}`;
    return { content: [{ type: "text", text }] };
  }
);
 
server.registerTool(
  "get_forecast",
  {
    description: "Get a 5-period weather forecast for a specific location",
    inputSchema: {
      latitude: z
        .number()
        .min(-90)
        .max(90)
        .describe("Latitude of the location"),
      longitude: z
        .number()
        .min(-180)
        .max(180)
        .describe("Longitude of the location"),
    },
  },
  async ({ latitude, longitude }) => {
    const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
    const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
 
    if (!pointsData) {
      return {
        content: [{
          type: "text",
          text: `Failed to fetch grid point for ${latitude}, ${longitude}. Only US locations are supported.`,
        }],
      };
    }
 
    const forecastUrl = pointsData.properties?.forecast;
    if (!forecastUrl) {
      return {
        content: [{ type: "text", text: "Could not find forecast URL in grid data" }],
      };
    }
 
    const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
    if (!forecastData) {
      return {
        content: [{ type: "text", text: "Failed to retrieve forecast" }],
      };
    }
 
    const periods = (forecastData.properties?.periods ?? []).slice(0, 5);
    if (periods.length === 0) {
      return {
        content: [{ type: "text", text: "No forecast periods available" }],
      };
    }
 
    const formatted = periods.map((p) =>
      [
        `${p.name ?? "Unknown"}:`,
        `  Temperature: ${p.temperature ?? "?"}°${p.temperatureUnit ?? "F"}`,
        `  Wind: ${p.windSpeed ?? "?"} ${p.windDirection ?? ""}`,
        `  ${p.shortForecast ?? "No forecast"}`,
      ].join("\n")
    );
 
    const text = `Forecast for (${latitude}, ${longitude}):\n\n${formatted.join("\n---\n")}`;
    return { content: [{ type: "text", text }] };
  }
);
 
// ============================================================
// Entry point
// ============================================================
 
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server running on stdio");
}
 
main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

# Build the TypeScript
npm run build
 
# Register with Claude Code
claude mcp add --transport stdio weather \
  -- node /absolute/path/to/weather-mcp-ts/build/index.js
 
# Or add to .mcp.json:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/absolute/path/to/weather-mcp-ts/build/index.js"]
    }
  }
}

# Python server
npx @modelcontextprotocol/inspector uv run weather.py
 
# TypeScript server
npx @modelcontextprotocol/inspector node build/index.js

# Add filesystem server (allows access to your home/projects directory)
claude mcp add --transport stdio filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem \
     /Users/$(whoami)/projects \
     /tmp
 
# Add Brave Search server
claude mcp add --transport stdio \
  --env BRAVE_API_KEY=your-api-key-here \
  brave-search \
  -- npx -y @modelcontextprotocol/server-brave-search

claude mcp list
# Output:
# filesystem  stdio  npx -y @modelcontextprotocol/server-filesystem ...
# brave-search  stdio  npx -y @modelcontextprotocol/server-brave-search

# Confirm the file was created
cat /tmp/async-notes.md