How to create an MCP server in TypeScript from scratch

In this tutorial, we will build a small server in TypeScript, advertise a tool called somar and test it with a local MCP client. The example does not access files, network or external accounts, so it is a safe start to understand the full cycle.

In this article you will see:

• The role of an MCP server
• How to create a tool in TypeScript
• How to test the local connection
• How to connect the server to a host

What is an MCP server and where it fits

MCP stands for Model Context Protocol, an open protocol for connecting AI applications to tools and context sources. The host is the application the person uses, such as an assistant or editor. It creates an MCP client, which talks to the server responsible for exposing resources and tools.

The official MCP architecture diagram shows this separation. Your server is not, by itself, an agent that decides what to do. It publishes described capabilities so a compatible host can discover them and call them.

This helps keep integration organized. One service can expose a search, another can query tasks and another can read authorized data. The host decides when to call each tool according to the conversation and the available permissions.

Before creating an MCP server in TypeScript

You need Node.js 20 or higher and a TypeScript project run with tsx. On October 27, 2026, the current versions of the MCP SDK for server and client were 2.4.0, and the package declares compatibility with Node.js starting from version 20.

The example uses Zod to validate the received arguments. This validation avoids accepting values outside the expected contract and makes the parameter description available to the MCP client.

Create a directory and initialize the package. Then use this package.json as a base and run npm install:

{
  "name": "mcp-server-demo",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "tsx src/server.ts",
    "test": "tsx src/client.ts"
  },
  "dependencies": {
    "@modelcontextprotocol/client": "2.4.0",
    "@modelcontextprotocol/server": "2.4.0",
    "zod": "4.2.0"
  },
  "devDependencies": {
    "tsx": "4.23.15"
  }
}

The type enables ES modules in Node.js. The scripts call the server and client without requiring a separate build step. The current documentation for the Model Context Protocol TypeScript SDK gathers examples and migration notes for version 2.

Step 1: prepare the MCP server project

Create src/server.ts and register a tool with two numeric inputs. The server uses STDIO transport, in which protocol messages pass through the standard stream of the local process.

import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod/v4";

serveStdio(() => {
  const server = new McpServer({ name: "servidor-mcp-demo", version: "1.0.0" });

  server.registerTool(
    "somar",
    {
      description: "Soma dois números e devolve o resultado.",
      inputSchema: z.object({
        a: z.number().describe("Primeiro número"),
        b: z.number().describe("Segundo número")
      })
    },
    async ({ a, b }) => ({
      content: [{ type: "text", text: String(a + b) }]
    })
  );

  return server;
});

McpServer organizes the capabilities published by the process. registerTool defines the name, description, input schema and the function that will be executed. The function returns a text block in the format expected by the protocol.

The example tool only calculates the sum. In a real application, replace this logic with a bounded task, such as querying an order or looking up internal information. Start with read operations and keep data mutating operations out of the first prototype.

Step 2: register the add tool

To confirm the server responds, create src/client.ts. This client starts the process over STDIO transport, lists the published tools and calls somar with values 2 and 3.

import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

const client = new Client({ name: "mcp-server-test", version: "1.0.0" });
const transport = new StdioClientTransport({
  command: process.execPath,
  args: ["--import", "tsx", "src/server.ts"]
});

try {
  await client.connect(transport);
  const { tools } = await client.listTools();
  console.log(`tools=${tools.map((tool) => tool.name).join(",")}`);
  const result = await client.callTool({ name: "somar", arguments: { a: 2, b: 3 } });
  console.log(`result=${result.content.map((part) => part.type === "text" ? part.text : "").join("")}`);
} finally {
  await client.close();
}

Run npm test. The expected result in this example is tools=somar and result=5. The listing confirms the client discovered the tool; the second line confirms the server processed the call and returned the content.

If the process closes without a response, first check if the directory contains src/server.ts and src/client.ts, if the packages are installed and if Node.js meets the minimum requirement. Diagnostic messages should go to stderr, not to stdout, because STDIO transport reserves the standard stream for the protocol.

How to connect the MCP server to a host

After local testing, register the process in an MCP compatible host. Each application has its own configuration format and approval policy, so follow the host specific documentation instead of copying an example from another editor.

In the guide to configure MCP in VS Code, see how to add a server to the client. To understand a MCP tool case focused on agents, also read about the Retrieve from Work IQ.

Before sharing the server, define what data it can read, who can call it and which actions require confirmation. Do not put tokens or passwords in code, in tool arguments or in log messages. If a tool changes files, sends messages or triggers payments, limit the scope and test human confirmation.

Keep descriptions short and specific. A tool called somar with inputs a and b communicates its intent better than a generic tool called executar. For each tool, say what it does, which arguments it accepts and what happens on error.