Build Your First MCP Server in 10 Minutes with TypeScript

How to Build Your First MCP Server in 10 Minutes

The Model Context Protocol (MCP) enables developers to expose custom tools directly to AI assistants. This guide demonstrates how to build a functional server using the @modelcontextprotocol/sdk in under 30 lines of code. It uses a simple stdio transport to facilitate communication between the AI client and the server process.

Why This Matters

While theoretical AI models are limited by their training data, the Model Context Protocol provides a standardized interface for real-time data access. By using stdio as a transport layer, developers can integrate tools into local environments like Claude Desktop or Cursor without the complexity of managing network protocols or authentication for local execution. This reduces the friction of turning internal APIs and database queries into actionable AI tools.

The technical reality of MCP lies in its use of Zod for input validation and JSON-RPC over stdio. This ensures that the AI assistant receives structured feedback while the server handles the heavy lifting of API interaction. Abstracting these communication layers allows engineers to focus on tool logic rather than the plumbing of agent-to-tool connectivity.

Key Insights

• The McpServer class manages discovery by providing metadata like name and version to AI clients (2026).
• StdioServerTransport facilitates local communication where the AI client launches the server as a child process.
• Tool registration requires a Zod schema to validate LLM-generated arguments before the handler executes.
• MCP Inspector allows for terminal-based debugging of server tools via a web UI before client deployment.
• The SDK handles content block formatting, allowing tools to return structured text or image data to the assistant.

Working Examples

A complete MCP server implementation in TypeScript that fetches weather data.

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

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

server.registerTool(
  "get-weather",
  {
    title: "Get Weather",
    description: "Get current weather for a city",
    inputSchema: z.object({
      city: z.string().describe("City name"),
    }),
  },
  async ({ city }) => {
    const res = await fetch(`https://wttr.in/${encodeURIComponent(city)}?format=j1`);
    const data = await res.json();
    const current = data.current_condition[0];
    return {
      content: [
        {
          type: "text",
          text: `${city}: ${current.temp_C}°C, ${current.weatherDesc[0].value}`,
        },
      ],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Weather MCP server running on stdio");

Configuration for connecting the MCP server to Claude Desktop.

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["tsx", "/full/path/to/my-mcp-server/server.ts"]
    }
  }
}

Practical Applications

• Internal API Exposure: Companies can wrap existing REST endpoints as MCP tools to allow agents to fetch internal data; Pitfall: Failing to implement read-only restrictions may lead to unauthorized data modification.
• Database Querying: Developers can register tools that run SQL queries against dev databases; Pitfall: Providing broad access without schema limits can result in the AI exposing sensitive metadata.
• Local File Operations: AI assistants can be granted permissions to read or search project files through dedicated tool handlers; Pitfall: Insecure file path handling could lead to directory traversal vulnerabilities.

References:

• https://dev.to/nebulagg/how-to-build-your-first-mcp-server-in-10-minutes-319
• github.com/modelcontextprotocol/typescript-sdk