A TypeScript server with the official SDK

Your first MCP server in TypeScript (with the official SDK)

So far we've talked about theory. In this lesson you'll write and run your first MCP server in TypeScript, using the official MCP SDK. Don't worry if you've never programmed in TypeScript: we'll define every term and copy the code in small pieces. By the end you'll have a server that exposes a tool (a tool that adds two numbers) and that Claude will actually be able to use.

What you'll learn

• What TypeScript is and why the official SDK uses it (it's JavaScript with types: labels that say what kind of data each thing expects, so errors surface before running).
• How to start a Node project with npm and install the SDK.
• How to create an McpServer, register a tool with a Zod schema, and connect it over stdio.
• How to run your server and register it in Claude Code with claude mcp add.

Before you start: the minimum vocabulary

• Node.js: the program that runs JavaScript/TypeScript outside the browser.
• npm: Node's package manager — it installs libraries (other people's code) for you.
• SDK: Software Development Kit; an official toolbox that saves you from writing the protocol by hand. Ours is @modelcontextprotocol/sdk.
• Zod: a library for validating data. We use it to describe what your tool receives (for example, "two numbers") and to have the SDK reject anything that doesn't fit.
• stdio: standard input/output. It's the "pipe" through which your server and the host talk when they run on the same machine. We saw it in the transports lesson.

Step by step

1. Create the folder and start the project. npm init -y builds a package.json (your project's info card) with default values, without asking you anything.

mkdir mi-servidor-mcp
cd mi-servidor-mcp
npm init -y

2. Enable modern modules. Open package.json and add "type": "module". This tells Node you're going to use import (the modern form) instead of require.

{
  "name": "mi-servidor-mcp",
  "version": "1.0.0",
  "type": "module"
}

3. Install the official SDK and Zod. (dotenv is optional, only if later you want to read environment variables such as secret keys.)

npm install @modelcontextprotocol/sdk zod
# optional, for environment variables:
npm install dotenv

4. Write the server. Create a file index.ts with this content. We explain it below, block by block.

// We bring in the pieces from the official SDK and from Zod.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 1) We create the server. name and version identify your server to the host.
const server = new McpServer({
  name: "demo",
  version: "1.0.0",
});

// 2) We register a tool called "suma".
//    The second argument is the Zod schema: it describes what it receives (two numbers).
//    The third is the function that runs when the model calls the tool.
server.tool(
  "suma",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);

// 3) We open the stdio transport and connect the server.
//    From here on, the server stays listening and ready to respond.
const transport = new StdioServerTransport();
await server.connect(transport);

Notice the pattern: you create the server → register tools → connect a transport. Those three lines are the skeleton of any MCP server in TypeScript.

5. Run the server. We use tsx, a tool that runs TypeScript directly, without compiling by hand. npx downloads and runs it on the fly.

npx tsx index.ts

You won't see much: the server stays waiting for messages over stdio. That's fine — it's its normal behavior. Close it with Ctrl+C.

6. Register it in Claude Code. This is how the host knows how to start your server and use its tool.

claude mcp add demo -- npx tsx /ruta/absoluta/a/index.ts

Now, inside Claude Code, ask it something like "add 21 and 21 with the demo tool" and you'll see your server in action.

Key moments in the video

• 2
  — Project setup: starting with npm, installing the SDK, and getting everything ready to write the server. Follow along with steps 1–3 above.
• 4
  — server.tool: how you register a tool and why the schema (in our case, Zod) is the key part. It's the heart of this lesson — watch it with step 4 beside you.

Quick glossary

• TypeScript: JavaScript with types; catches errors before running.
• npm / npm init -y / npm install: start the project and install libraries.
• "type": "module": enables the modern import syntax in Node.
• McpServer: the SDK class that represents your server.
• server.tool(name, schema, handler): registers a tool (name, what it receives, what it does).
• Zod / z.number(): describes and validates the data that goes into your tool.
• StdioServerTransport: the transport that connects server and host over stdio.
• npx tsx: runs your .ts without compiling by hand.
• claude mcp add: registers your server in Claude Code.

To download

• 📄 Commented code — TypeScript server (PDF): the complete server, line by line, with the install and run commands ready to copy.
• 🧰 Skill pack — mcp-ts-starter: a Claude Code skill with a minimal server that already works (two example tools) to start your next project in seconds.

Before you move on

If you take away one idea, let it be this: every MCP server in TypeScript is create the server → register tools → connect a transport. You've already done it once; the rest of the course is variations on this same pattern. In the next lesson we add more than one tool and real data.