Building Your First Model Context Protocol (MCP) Server with TypeScript and Zod

Anthropic's Model Context Protocol (MCP) provides an open standard for connecting AI models to external tools and data sources. A developer demonstrates building a production-grade MCP server using TypeScript, the official @modelcontextprotocol/sdk, and Zod for runtime validation, treating the AI architecture through the lens of modern distributed systems.

If you’ve been building AI agents or working with Large Language Models recently, you’ve likely hit the integration wall. Historically, connecting an LLM like Claude or GPT-4 to external environments—such as querying a production database, checking system logs, or interacting with a local file system—required building ad-hoc, brittle integration layers. Every single AI framework required bespoke tool definitions, custom JSON-parsing loops, and hardcoded prompt engineering just to handle basic errors. Building these custom integrations felt remarkably like the early days of web development before HTTP standardization, where every browser vendor implemented proprietary rendering engines, forcing developers to maintain fragmented codebases. Enter the Model Context Protocol MCP . Developed by Anthropic, MCP establishes an open, universal standard for connecting AI models to data sources and tools. In this comprehensive guide, we will dive deep into the architectural foundations of MCP, explore how it maps cleanly to modern web development paradigms like microservices, and build a production-grade, self-contained MCP server from scratch using TypeScript, the official @modelcontextprotocol/sdk , and Zod for strict runtime input validation. To truly grasp why building an MCP server in TypeScript is a game-changer for AI application development, we have to look at how LLMs historically interacted with external environments. In a traditional setup, when an AI model needs to fetch data, developers write custom code that wraps APIs in rigid prompt instructions. However, models are probabilistic. They generate text token by token, meaning they are prone to subtle hallucinations regarding data types, missing required arguments, or formatting structural JSON incorrectly. MCP solves this fragmentation by treating the AI architecture through the lens of modern distributed systems, mapping the Model Context Protocol Client-Server Architecture directly to the classic Microservices Architecture via REST and gRPC : When an AI model requires data or needs to execute an action, the LLM Host does not execute custom Python or TypeScript scripts directly. Instead, it queries the connected MCP servers to discover available tools, inspects their schemas, and delegates execution. The MCP server processes the request, interacts with the local system, and returns a standardized response payload. This decoupling ensures that security boundaries are strictly maintained: the LLM never executes arbitrary code on your system; it merely requests that an explicit, sandboxed MCP tool executes a predefined function. At its core, MCP is not a complex machine learning framework. Rather, it is a clean, rigorously engineered JSON-RPC 2.0 protocol running over structured input/output streams. When you boot an MCP server, it does not immediately start listening for AI tokens. Instead, it enters a precise, multi-phase lifecycle governed by initialization handshakes, capability negotiations, and continuous state synchronization. Communication between the MCP Host and the MCP Server must be decoupled from the transport mechanism. The TypeScript SDK provides abstract transport interfaces, primarily supporting two modes: child process.spawn . Communication happens entirely through standard input process.stdin and standard output process.stdout . This is exceptionally secure because no network ports are opened, eliminating entire classes of network-based vulnerabilities. Logs and debugging statements must be strictly routed to standard error process.stderr , as any stray console.log on stdout will corrupt the JSON-RPC message stream.Once the transport channel is established, neither side assumes the other's capabilities. The handshake proceeds through a rigid sequence of JSON-RPC messages: initialize Request: initialize request to the server containing its protocol version and client capabilities. initialize Response: tools , resources , or prompts . notifications/initialized Notification:A common point of confusion for developers new to MCP is distinguishing between Tools and Resources . While both expose data to the LLM, their semantic contracts are fundamentally different: postgres://users/schema or file:///logs/error.log . Resources are passive; the LLM reads them to gather context In traditional web applications, input validation is important for security and data integrity. In AI agent architectures, strict input validation is an absolute necessity. Because Large Language Models generate text probabilistically, they are prone to subtle hallucinations regarding data types, missing required arguments, or formatting structural JSON incorrectly. When building an MCP server in TypeScript, you do not write manual if/else checks or ad-hoc regular expressions to validate incoming tool arguments. Instead, you rely on Zod , a TypeScript-first schema declaration and validation library. MCP bridges the gap between probabilistic text generation and deterministic backend execution by combining LLM tool declarations with strict, runtime schema enforcement via Zod. When you define an MCP tool using the TypeScript SDK, you pass a Zod schema alongside the tool's metadata: // Conceptual schema definition demonstrating how Zod enforces runtime safety const CreateUserSchema = z.object { username: z.string .describe "The unique handle for the user" , age: z.number .int .positive .describe "The user's age in years" , email: z.string .email .optional .describe "Optional contact email" } ; Under the hood, the MCP SDK serializes these Zod schemas into standard JSON Schema specifications during the tool discovery phase. When the LLM Host requests the list of available tools, it receives these explicit JSON Schemas. The host then injects these schemas into the LLM's system prompt or tool-calling grammar such as OpenAI's function calling or Anthropic's tool use blocks , constraining the model's output generation to match the expected structure. When the LLM decides to invoke the tool, it sends a JSON-RPC request containing the raw argument payload. The MCP server intercepts this payload and passes it directly through the Zod schema's .parse or .safeParse method: "age": "twenty-five" instead of the integer 25 , Zod catches the mismatch immediately. Expected number, received string at "age" . The MCP server catches this error, serializes it into a standardized JSON-RPC error response, and sends it back to the LLM. To truly master the mechanics of building an MCP server in TypeScript, it helps to map abstract protocol mechanics to familiar software engineering paradigms. Think of the LLM Host such as Claude Desktop or an enterprise agent runner as the Operating System Kernel . The kernel possesses high-level intelligence and scheduling capabilities managing the conversation, deciding the overarching goal , but it is intentionally stripped of direct drivers for every possible peripheral device in the universe. An MCP Server is analogous to a Device Driver e.g., a graphics driver, a printer driver, or a file system driver . Before an operating system can interact with a specialized RAID controller, the manufacturer must write a driver that adheres to the OS's strict kernel extension interfaces. Similarly, before an AI model can interact with a proprietary SQL database or a local Git repository, a developer must write an MCP server that adheres to the Model Context Protocol specification. If you have experience building modern web APIs, the architectural design of an MCP server will feel remarkably familiar. In a GraphQL server, you define a schema using the GraphQL SDL, mapping types, queries, and mutations. For every field in that schema, you write a resolver function that fetches the required data from a database, microservice, or cache. In an MCP server, the relationship between tools and their execution handlers mirrors GraphQL resolvers precisely: Let us examine a complete, self-contained MCP server designed for a SaaS context. This example implements a simulated customer support metrics and user lookup tool. It uses the official @modelcontextprotocol/sdk and zod for strict runtime input validation, communicating over standard input/output stdio streams with an MCP host. bash /usr/bin/env node / SaaS Customer Support MCP Server This self-contained TypeScript file sets up a Model Context Protocol MCP server using the official @modelcontextprotocol/sdk. It exposes a tool for querying user account metrics and fetching application logs, designed to integrate with an AI assistant or supervisor agent running inside an MCP-compatible host. / import { Server } from "@modelcontextprotocol/sdk/server/index.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js"; import { z } from "zod"; // ============================================================================ // Mock Database / SaaS Data Layer // ============================================================================ interface SaaSUser { id: string; email: string; plan: "free" | "pro" | "enterprise"; mrr: number; // Monthly Recurring Revenue status: "active" | "suspended" | "churned"; lastActive: string; } const MOCK USERS: Record<string, SaaSUser = { "usr 101": { id: "usr 101", email: "alice@acme-corp.com", plan: "enterprise", mrr: 499.00, status: "active", lastActive: "2023-10-25T14:32:00Z", }, "usr 102": { id: "usr 102", email: "bob@startup-io.net", plan: "pro", mrr: 49.00, status: "active", lastActive: "2023-10-24T09:15:00Z", }, }; const MOCK SYSTEM LOGS = 2023-10-25T14:30:00Z INFO System health nominal. DB connection pool: 12/50. 2023-10-25T14:31:12Z WARN Rate limit approached for client usr 102 92% capacity . 2023-10-25T14:32:00Z INFO User usr 101 successfully authenticated via OAuth2. ; // ============================================================================ // Server Initialization // ============================================================================ const server = new Server { name: "saas-support-mcp-server", version: "1.0.0", }, { capabilities: { tools: {}, resources: {}, }, } ; // ============================================================================ // Tool Schema Definitions Using Zod // ============================================================================ const GetUserMetricsSchema = z.object { userId: z.string .describe "The unique identifier of the user e.g., usr 101 " , } ; // ============================================================================ // Request Handlers Setup // ============================================================================ server.setRequestHandler ListToolsRequestSchema, async = { return { tools: { name: "get user metrics", description: "Retrieves billing, plan, and activity status for a given SaaS user.", inputSchema: { type: "object", properties: { userId: { type: "string", description: "The unique identifier of the user e.g., usr 101 ", }, }, required: "userId" , }, }, , }; } ; server.setRequestHandler CallToolRequestSchema, async request = { const { name, arguments: args } = request.params; if name === "get user metrics" { const parseResult = GetUserMetricsSchema.safeParse args ; if parseResult.success { throw new Error Invalid arguments for get user metrics: ${parseResult.error.message} ; } const { userId } = parseResult.data; const user = MOCK USERS userId ; if user { return { content: { type: "text", text: JSON.stringify { error: User with ID ${userId} not found. } , }, , isError: true, }; } return { content: { type: "text", text: JSON.stringify user, null, 2 , }, , }; } throw new Error Unknown tool: ${name} ; } ; // ============================================================================ // Resource Handlers Setup // ============================================================================ server.setRequestHandler ListResourcesRequestSchema, async = { return { resources: { uri: "saas://logs/system", name: "System Activity Logs", description: "Real-time diagnostic logs from the SaaS application backend.", mimeType: "text/plain", }, , }; } ; server.setRequestHandler ReadResourceRequestSchema, async request = { const { uri } = request.params; if uri === "saas://logs/system" { return { contents: { uri, mimeType: "text/plain", text: MOCK SYSTEM LOGS, }, , }; } throw new Error Resource not found: ${uri} ; } ; // ============================================================================ // Transport Connection & Execution // ============================================================================ async function main { const transport = new StdioServerTransport ; await server.connect transport ; console.error "SaaS Support MCP Server running on stdio" ; } main .catch error = { console.error "Fatal error in MCP server initialization:", error ; process.exit 1 ; } ; To fully master the mechanics of building an MCP server in TypeScript, let us examine the critical segments of the code above: Shebang and Environment Definition /usr/bin/env node : PATH . This is essential because MCP servers are frequently spawned as child processes by desktop host applications like Claude Desktop. Server Instance Configuration : Server instance from @modelcontextprotocol/sdk/server/index.js , passing server metadata name and version and an explicit capability map declaring that our server supports both tools and resources . Runtime Validation via Zod : GetUserMetricsSchema defines the expected shape of incoming arguments. When the LLM invokes get user metrics , the server intercepts the payload and executes .safeParse args . If the model hallucinates or passes incorrect types, Zod catches the mismatch immediately and formats a descriptive error message. Request Handler Routing : ListToolsRequestSchema , CallToolRequestSchema , ListResourcesRequestSchema , and ReadResourceRequestSchema . This clean separation ensures our server can dynamically advertise its capabilities and execute business logic safely. Transport Connection StdioServerTransport : main asynchronous function instantiates a standard input/output transport layer and connects the server instance. Crucially, all diagnostic logs are sent to process.stderr , preserving process.stdout exclusively for clean JSON-RPC message passing.As AI agents transition from passive chat assistants to active automation engines capable of executing code, modifying files, and calling enterprise APIs, security becomes paramount. The Model Context Protocol establishes a robust security posture through architectural isolation and the principle of least privilege: Building your first Model Context Protocol server in TypeScript opens up a world of robust, secure, and standardized AI application development. By moving away from brittle, ad-hoc integration layers and adopting a clean client-server architecture powered by JSON-RPC, TypeScript, and Zod, you can transform probabilistic Large Language Models into deterministic, highly capable autonomous agents. Whether you are building internal developer tools, enterprise support automations, or specialized data connectors, mastering MCP is an essential skill for modern AI engineers. Clone the SDK, set up your Zod schemas, and start building your first custom MCP server today The concepts and code demonstrated here are drawn directly from the comprehensive roadmap laid out in the book Model Context Protocol MCP & Computer Use. Standardizing Tool Integration, Vision-Driven Browser Automation, and Agent Governance in TypeScript , you can find it here http://tiny.cc/ModelContextProtocol . Check also the many other ebooks http://tiny.cc/ProgrammingBooks .