How to build an MCP server in TypeScript

npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/[email protected] @modelcontextprotocol/[email protected] zod@^4.2.0
npm install -D tsx@4

// A minimal, tested MCP server in TypeScript using the official v2 SDK.
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";

function createServer() {
  const server = new McpServer(
    { name: "text-tools", version: "1.0.0" },
    { capabilities: { tools: {}, resources: {} } }
  );

  // A tool that returns structured output. The outputSchema populates
  // structuredContent, so clients get typed data, not just a text blob.
  server.registerTool(
    "word_count",
    {
      title: "Word count",
      description: "Count words, characters, and sentences in a block of text.",
      inputSchema: z.object({ text: z.string() }),
      outputSchema: z.object({
        words: z.number(),
        characters: z.number(),
        sentences: z.number(),
      }),
    },
    async ({ text }) => {
      const words = text.trim().split(/\s+/).filter(Boolean);
      const sentences = text.split(/[.!?]+/).filter((s) => s.trim());
      const output = {
        words: words.length,
        characters: text.length,
        sentences: sentences.length,
      };
      return {
        content: [{ type: "text", text: JSON.stringify(output) }],
        structuredContent: output,
      };
    }
  );

  // A tool that returns plain text.
  server.registerTool(
    "slugify",
    {
      title: "Slugify",
      description: "Turn a title into a URL-safe slug.",
      inputSchema: z.object({ text: z.string() }),
    },
    async ({ text }) => {
      const slug = text
        .trim()
        .toLowerCase()
        .replace(/[^a-z0-9]+/g, "-")
        .replace(/^-+|-+$/g, "");
      return { content: [{ type: "text", text: slug }] };
    }
  );

  // A resource: read-only data a client can fetch without calling a tool.
  server.registerResource(
    "server-info",
    "info://server",
    { title: "Server info", mimeType: "text/plain" },
    async (uri) => ({
      contents: [
        { uri: uri.href, text: "text-tools v1.0.0: word_count, slugify" },
      ],
    })
  );

  return server;
}

// serveStdio owns the connection: it reads JSON-RPC from stdin and writes to
// stdout. Never write logs to stdout, it corrupts the protocol. Use stderr.
serveStdio(createServer);
console.error("text-tools MCP server running on stdio");

// Spawns the server over stdio and asserts the tools and resource work.
import assert from "node:assert/strict";
import { Client } from "@modelcontextprotocol/client";
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "server.ts"],
});

const client = new Client({ name: "test-client", version: "1.0.0" });
await client.connect(transport);

const { tools } = await client.listTools();
assert.deepEqual(tools.map((t) => t.name).sort(), ["slugify", "word_count"]);

const wc = await client.callTool({
  name: "word_count",
  arguments: { text: "Hello world. This works!" },
});
assert.deepEqual(wc.structuredContent, { words: 4, characters: 24, sentences: 2 });

const slug = await client.callTool({
  name: "slugify",
  arguments: { text: "Build an MCP Server!" },
});
assert.equal(slug.content[0].text, "build-an-mcp-server");

const info = await client.readResource({ uri: "info://server" });
assert.match(info.contents[0].text, /text-tools v1\.0\.0/);

console.log("ALL ASSERTIONS PASSED");
await client.close();

npx tsx test-client.ts

text-tools MCP server running on stdio
ALL ASSERTIONS PASSED

{
  "mcpServers": {
    "text-tools": {
      "command": "npx",
      "args": ["-y", "tsx", "/Users/you/text-tools/server.ts"]
    }
  }
}