Building an MCP Server in TypeScript: Node.js Tools for AI Agents

TypeScript's Advantage for MCP

TypeScript brings compile-time type safety to MCP server development. Every tool's input schema, output format, and error response can be checked before the code ever runs. When an AI agent sends malformed parameters, TypeScript MCP servers catch the mismatch at the validation layer — not as a runtime crash in your business logic.

The official @modelcontextprotocol/sdk package provides first-class TypeScript support with a McpServer class that mirrors what FastMCP does in Python.

Project Setup

Initialize a TypeScript project and install dependencies:

flowchart LR
    HOST(["MCP host<br/>Claude Desktop or IDE"])
    CLIENT["MCP client"]
    subgraph SERVERS["MCP Servers"]
        S1["Filesystem server"]
        S2["GitHub server"]
        S3["Postgres server"]
        SX["Custom tool server"]
    end
    LLM["LLM session"]
    OUT(["Grounded action"])
    HOST <--> CLIENT
    CLIENT <-->|stdio or HTTP+SSE| S1
    CLIENT <--> S2
    CLIENT <--> S3
    CLIENT <--> SX
    CLIENT --> LLM --> OUT
    style HOST fill:#f1f5f9,stroke:#64748b,color:#0f172a
    style CLIENT fill:#4f46e5,stroke:#4338ca,color:#fff
    style OUT fill:#059669,stroke:#047857,color:#fff

# Terminal commands (shown as comments for clarity)
# npm init -y
# npm install @modelcontextprotocol/sdk zod
# npm install -D typescript @types/node tsx

Create a minimal tsconfig.json:

# tsconfig.json (JSON format)
# {
#   "compilerOptions": {
#     "target": "ES2022",
#     "module": "Node16",
#     "moduleResolution": "Node16",
#     "outDir": "./dist",
#     "strict": true
#   }
# }

Defining Tools with Zod Schemas

The TypeScript SDK uses Zod for input validation. Each tool defines its parameters as a Zod schema, and the SDK converts it to JSON Schema for the MCP protocol automatically:

# file_tools.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import fs from "fs/promises";
import path from "path";

const ALLOWED_DIR = "/data/workspace";

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

// Tool: Read a file
server.tool(
  "read_file",
  "Read the contents of a file within the workspace directory",
  {
    filePath: z
      .string()
      .describe("Relative path to the file within the workspace"),
  },
  async ({ filePath }) => {
    const resolved = path.resolve(ALLOWED_DIR, filePath);

    // Security: prevent path traversal
    if (!resolved.startsWith(ALLOWED_DIR)) {
      return {
        content: [
          { type: "text", text: "Error: path traversal not allowed" },
        ],
      };
    }

    try {
      const content = await fs.readFile(resolved, "utf-8");
      return {
        content: [{ type: "text", text: content }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: "Error reading file: " + String(err),
          },
        ],
        isError: true,
      };
    }
  }
);

The server.tool() method takes four arguments: the tool name, a description, a Zod schema object for parameters, and the async handler function. The handler receives validated, typed parameters — no manual parsing needed.

Adding More Tools

Extend the server with a tool that lists directory contents:

server.tool(
  "list_directory",
  "List files and directories in a workspace path",
  {
    dirPath: z
      .string()
      .default(".")
      .describe("Relative directory path (default: workspace root)"),
    includeHidden: z
      .boolean()
      .default(false)
      .describe("Include hidden files starting with a dot"),
  },
  async ({ dirPath, includeHidden }) => {
    const resolved = path.resolve(ALLOWED_DIR, dirPath);

    if (!resolved.startsWith(ALLOWED_DIR)) {
      return {
        content: [{ type: "text", text: "Error: path traversal" }],
        isError: true,
      };
    }

    const entries = await fs.readdir(resolved, { withFileTypes: true });
    const filtered = includeHidden
      ? entries
      : entries.filter((e) => !e.name.startsWith("."));

    const listing = filtered.map((entry) => ({
      name: entry.name,
      type: entry.isDirectory() ? "directory" : "file",
    }));

    return {
      content: [
        { type: "text", text: JSON.stringify(listing, null, 2) },
      ],
    };
  }
);

Zod provides default values, optional fields, and rich descriptions — all of which flow into the JSON Schema that agents consume during tool discovery.

Running the Server

For stdio transport (local agent integration):

import { StdioServerTransport } from
  "@modelcontextprotocol/sdk/server/stdio.js";

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("FileTools MCP server running on stdio");
}

main().catch(console.error);

For HTTP transport (remote access):

import { StreamableHTTPServerTransport } from
  "@modelcontextprotocol/sdk/server/streamableHttp.js";
import express from "express";

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new StreamableHTTPServerTransport({
    sessionIdGenerator: undefined,  // stateless mode
  });
  res.on("close", () => transport.close());
  await server.connect(transport);
  await transport.handleRequest(req, res);
});

app.listen(8002, () => {
  console.log("MCP server listening on port 8002");
});

Error Handling Patterns

TypeScript MCP servers should return errors as content with the isError flag rather than throwing exceptions. This ensures the agent receives a structured error message it can reason about:

server.tool(
  "divide",
  "Divide two numbers",
  {
    numerator: z.number(),
    denominator: z.number(),
  },
  async ({ numerator, denominator }) => {
    if (denominator === 0) {
      return {
        content: [
          { type: "text", text: "Cannot divide by zero" },
        ],
        isError: true,
      };
    }
    return {
      content: [
        { type: "text", text: String(numerator / denominator) },
      ],
    };
  }
);

Deployment Options

Package the server as a Docker container for production. The stdio transport works well for local development, while streamable HTTP is the right choice for servers that need to be shared across teams or accessed by cloud-hosted agents. Use environment variables for configuration and secrets — never hardcode API keys or database credentials in the server code.

FAQ

Can I use the TypeScript MCP SDK with Deno or Bun?

The SDK targets Node.js, but both Deno and Bun have strong Node.js compatibility. Bun works out of the box for most SDK features. Deno requires the --allow-net and --allow-read permissions and npm compatibility mode. Test thoroughly with your chosen runtime.

How do I add authentication to a TypeScript MCP server?

For HTTP transport, add middleware before the MCP handler that validates API keys or OAuth tokens. For stdio transport, authentication is typically handled by the process launcher (the agent runtime), since stdio servers run as local subprocesses with inherited permissions.

What is the difference between isError: true and throwing an exception?

Returning isError: true in the content gives the agent a structured error message it can use to retry or adjust its approach. Throwing an exception results in a JSON-RPC internal error (-32603) with less context. Always prefer returning errors in content for expected failure cases like invalid inputs or missing resources.

---

#MCP #TypeScript #Nodejs #AIAgents #AgenticAI #LearnAI #AIEngineering