---
title: "Building an MCP Server in TypeScript: Node.js Tools for AI Agents"
description: "Create a fully typed MCP server in TypeScript using the official MCP SDK, with tool handlers, Zod validation, and deployment strategies for exposing Node.js services to AI agents."
canonical: https://callsphere.ai/blog/building-mcp-server-typescript-nodejs-tools-ai-agents
category: "Learn Agentic AI"
tags: ["MCP", "TypeScript", "Node.js", "AI Agents", "Agentic AI"]
author: "CallSphere Team"
published: 2026-03-17T00:00:00.000Z
updated: 2026-05-07T16:31:33.573Z
---

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

> Create a fully typed MCP server in TypeScript using the official MCP SDK, with tool handlers, Zod validation, and deployment strategies for exposing Node.js services to 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:

```mermaid
flowchart LR
    HOST(["MCP host
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
```

```python
# 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`:

```python
# 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:

```python
# 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:

```python
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):

```python
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):

```python
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:

```python
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

---

Source: https://callsphere.ai/blog/building-mcp-server-typescript-nodejs-tools-ai-agents