How to build an MCP server in TypeScript

curl -sL https://cdn.jsdelivr.net/npm/@modelcontextprotocol/sdk@latest/dist/esm/types.js \
  | grep -E "LATEST_PROTOCOL_VERSION|SUPPORTED_PROTOCOL_VERSIONS"

# export const LATEST_PROTOCOL_VERSION = '2025-11-25';
# export const SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION,
#   '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07'];

mkdir mcp-weather && cd mcp-weather
npm init -y
npm install express
npm install -D typescript tsx @types/node @types/express
npx tsc --init

import express from "express"

const app = express()
app.use(express.json())

const PROTOCOL_VERSION = "2026-07-28"
const SERVER_INFO = { name: "weather", version: "1.0.0" }

app.post("/mcp", async (req, res) => {
  const { id, method, params } = req.body ?? {}
  // header validation and dispatch go here
})

// Statelessness: GET and DELETE have nothing to act on
app.get("/mcp", (_req, res) => res.status(405).end())
app.delete("/mcp", (_req, res) => res.status(405).end())

app.listen(3000)

export const HEADER_MISMATCH = -32020

/** Header names are case-insensitive per RFC 9110 — never match exact case. */
export function validateHeaders(req: {
  headers: Record<string, unknown>
  body: { method?: string; params?: Record<string, unknown> }
}): string | null {
  const h = (name: string) => req.headers[name.toLowerCase()] as string | undefined

  const version = h("mcp-protocol-version")
  const method  = h("mcp-method")
  const name    = h("mcp-name")

  if (!version) return "MCP-Protocol-Version is required on every POST"
  if (!method)  return "Mcp-Method is required on every request"

  if (method !== req.body.method) {
    return "Mcp-Method does not match the body method"
  }

  const meta = (req.body.params?._meta ?? {}) as Record<string, unknown>
  const metaVersion = meta["io.modelcontextprotocol/protocolVersion"]
  if (metaVersion && version !== metaVersion) {
    return "MCP-Protocol-Version does not match _meta protocolVersion"
  }

  // Mcp-Name is required on these three, and must match the body
  const NAMED = ["tools/call", "resources/read", "prompts/get"]
  if (NAMED.includes(req.body.method ?? "")) {
    const target = (req.body.params?.name ?? req.body.params?.uri) as string | undefined
    if (!name) return "Mcp-Name is required on " + req.body.method
    if (name !== target) return "Mcp-Name does not match the body"
  }

  return null
}

app.post("/mcp", async (req, res) => {
  const { id, method, params } = req.body ?? {}

  const headerError = validateHeaders(req)
  if (headerError) {
    return res.status(400).json({
      jsonrpc: "2.0", id,
      error: { code: HEADER_MISMATCH, message: headerError },
    })
  }
  // … dispatch
})

function discover() {
  return {
    resultType: "complete",
    supportedVersions: ["2026-07-28"],
    capabilities: { tools: {} },
    _meta: {
      "io.modelcontextprotocol/serverInfo": SERVER_INFO,
    },
  }
}

const TOOLS = [
  {
    name: "get_weather",
    description: "Current conditions for a location",
    inputSchema: {
      type: "object",
      properties: { location: { type: "string" } },
      required: ["location"],
    },
  },
]

function toolsList() {
  return {
    resultType: "complete",   // MCP-RES-001
    tools: TOOLS,             // deterministic order — MCP-RES-007
    ttlMs: 3600000,           // MCP-CAC-001
    cacheScope: "public",     // MCP-CAC-002
    _meta: { "io.modelcontextprotocol/serverInfo": SERVER_INFO },
  }
}

async function toolsCall(params: { name: string; arguments?: Record<string, unknown> }) {
  if (params.name !== "get_weather") {
    throw { code: -32602, message: `Unknown tool: ${params.name}` }
  }

  const location = params.arguments?.location
  if (typeof location !== "string") {
    throw { code: -32602, message: "location is required and must be a string" }
  }

  const conditions = await lookUpWeather(location)

  return {
    resultType: "complete",
    content: [{ type: "text", text: conditions.summary }],
    structuredContent: conditions,
    _meta: { "io.modelcontextprotocol/serverInfo": SERVER_INFO },
  }
}

app.post("/mcp", async (req, res) => {
  const { id, method, params } = req.body ?? {}

  const headerError = validateHeaders(req)
  if (headerError) {
    return res.status(400).json({
      jsonrpc: "2.0", id, error: { code: HEADER_MISMATCH, message: headerError },
    })
  }

  try {
    let result
    switch (method) {
      case "server/discover": result = discover();            break
      case "tools/list":      result = toolsList();           break
      case "tools/call":      result = await toolsCall(params); break
      default:
        // MCP-ERR-002: 404 *and* -32601, not just the JSON-RPC error
        return res.status(404).json({
          jsonrpc: "2.0", id,
          error: { code: -32601, message: `Method not found: ${method}` },
        })
    }
    return res.json({ jsonrpc: "2.0", id, result })
  } catch (err: any) {
    return res.status(err.code === -32602 ? 400 : 500).json({
      jsonrpc: "2.0", id,
      error: { code: err.code ?? -32603, message: err.message ?? "Internal error" },
    })
  }
})

curl -i http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/list",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

# Mcp-Method says list, the body says call → expect 400 / -32020
curl -i http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_weather"}}'