TypeScript MCP server debugging

Debugging Zod schema validation errors

The MCP TypeScript SDK validates tool arguments against your Zod schema before calling the handler. When validation fails, it throws a ZodError. The default error message (ZodError: [...]) is a JSON array that's hard to read. Use ZodError.flatten() to get a structured breakdown of which fields failed:

import { z } from 'zod';

const searchSchema = z.object({
  query: z.string().min(1, 'query must not be empty'),
  limit: z.number().int().min(1).max(100).optional(),
  filter: z.enum(['active', 'archived', 'all']).optional(),
});

// In a catch block or error handler:
try {
  searchSchema.parse(args);
} catch (err) {
  if (err instanceof z.ZodError) {
    // Flatten gives you fieldErrors and formErrors separately
    const flat = err.flatten();
    console.error('Validation failed:', JSON.stringify(flat, null, 2));
    // Output:
    // {
    //   "fieldErrors": {
    //     "query": ["query must not be empty"],
    //     "filter": ["Invalid enum value. Expected 'active' | 'archived' | 'all', received 'deleted'"]
    //   },
    //   "formErrors": []
    // }
  }
}

The MCP SDK calls parse() on your schema before invoking the handler — you never see these errors in your handler code. To observe them during development, wrap the schema parse in your own validation step and log the result:

server.tool('search_documents', searchSchema, async (args) => {
  // At this point, args is already validated and typed by Zod
  // But if you want to debug what the raw args look like before validation:
  // Use logger.debug() or a DEBUG flag — never console.log() in stdio mode
  logger.debug({ rawArgs: args }, 'handler called with typed args');
});

When the MCP client sends arguments that fail Zod validation, the SDK returns a JSON-RPC error to the client (not an isError: true tool result). The MCP Inspector shows this as a red error in the Protocol tab rather than a yellow error in the Result panel.

Improving async stack traces

TypeScript MCP server handlers are async functions. When an error is thrown inside an await call several levels deep, the default Node.js stack trace often starts at the Promise boundary and doesn't show the originating call. In Node.js 22, async stack traces are significantly better, but you can still tune them:

# Increase stack trace depth (default is 10 frames, which is often too few)
NODE_OPTIONS="--stack-trace-limit=50" node dist/index.js

# In code — set this at startup before any async operations begin
Error.stackTraceLimit = 50;

For async errors that still show truncated stacks, use the cause property to chain errors with context:

server.tool('get_document', getDocSchema, async (args) => {
  try {
    const row = await db.query('SELECT * FROM documents WHERE id = $1', [args.id]);
    if (!row) {
      throw new Error(`Document ${args.id} not found`);
    }
    return { content: [{ type: 'text', text: JSON.stringify(row) }] };
  } catch (err) {
    // Chain the original error as `cause` to preserve the original stack
    throw new Error(`get_document failed for id=${args.id}`, { cause: err });
  }
});

The { cause: err } pattern (available in Node 16.9+, TypeScript 4.6+) creates a causal chain in the error. When you log or inspect the error, you see both the handler-level context and the original database error with its stack.

ts-node vs tsc: source maps for debugging

The key difference for debugging:

For debugging sessions, ts-node eliminates the most common mistake: hitting a breakpoint in compiled code that's one commit behind your current source. Configure ts-node for debugging in VS Code's launch.json:

// .vscode/launch.json — ts-node configuration
{
  "name": "Debug MCP Server (ts-node, no build)",
  "type": "node",
  "request": "launch",
  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/ts-node",
  "runtimeArgs": ["--esm"],
  "program": "${workspaceFolder}/src/index.ts",
  "env": {
    "DATABASE_URL": "postgres://localhost/mydb",
    "TS_NODE_PROJECT": "${workspaceFolder}/tsconfig.json"
  },
  "sourceMaps": true,
  "console": "integratedTerminal"
}

For ESM projects (the standard for new TypeScript MCP servers), use --esm flag with ts-node. For CommonJS projects, omit it.

Debugging with Vitest (test-time debugging)

The fastest way to debug a specific tool handler bug is to write a Vitest test that reproduces it, then run Vitest with the Node.js inspector. This lets you debug the tool handler code with a breakpoint, without involving the MCP protocol at all:

# Run Vitest with the Node debugger (pauses at start)
node --inspect-brk ./node_modules/.bin/vitest run src/tools/search.test.ts

# Or using the vitest CLI flag (Vitest 1.0+)
vitest --inspect-brk run src/tools/search.test.ts

Then attach VS Code with the attach configuration (port 9229). The test runs normally until it hits a breakpoint in your tool handler — you can step through the handler, inspect variables, and diagnose the failure at the exact line where it goes wrong.

// src/tools/search.test.ts — minimal reproduction test
import { describe, it, expect } from 'vitest';
import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { createServer } from '../index.js';

describe('search_documents', () => {
  it('returns empty array for unknown filter value', async () => {
    const [serverTransport, clientTransport] = InMemoryTransport.createLinkedPair();
    const server = createServer({ db: mockDb });
    await server.connect(serverTransport);

    const client = new Client({ name: 'test', version: '1' }, { capabilities: {} });
    await client.connect(clientTransport);

    // Set a breakpoint in the search handler and call it with the failing args
    const result = await client.callTool('search_documents', {
      query: '',           // empty string — does this trigger the right error?
      filter: 'deleted',  // invalid enum — does Zod catch this?
    });

    expect(result.isError).toBe(true);
    await client.close();
  });
});

The InMemoryTransport keeps everything in-process — the test, the client, and the server handler all run in one Node.js process, making it easy to set breakpoints in handler code without any MCP transport complexity.

Common TypeErrors in MCP handlers

These are the most frequent TypeErrors developers encounter in TypeScript MCP handlers, with their root causes and fixes:

TypeScript strict mode gotchas in MCP handlers

TypeScript strict mode ("strict": true in tsconfig.json) is strongly recommended for MCP servers — it catches the null/undefined access patterns above at compile time. But it introduces some friction in MCP handler code:

// PROBLEM: strict mode flags this because args.filter could be undefined
server.tool('search', schema, async (args: z.infer) => {
  const results = await db.search(args.query, args.filter.toUpperCase()); // ERROR: filter possibly undefined
});

// FIX: use optional chaining or explicit null check
const results = await db.search(args.query, args.filter?.toUpperCase());
// or
const results = await db.search(args.query, args.filter ?? 'active');

// PROBLEM: TypeScript doesn't know the MCP result shape satisfies the SDK type
return { content: [{ type: 'text', text: output }] };  // type 'string' is not assignable to type 'TextContent'

// FIX: explicit type annotation matches the SDK's ContentBlock type
return {
  content: [{ type: 'text' as const, text: output }],  // 'as const' narrows 'string' to literal 'text'
};

The as const pattern for the type field is the most common TypeScript-specific fix in MCP handler code — without it, TypeScript infers type: string instead of type: 'text', which doesn't satisfy the SDK's TextContent type.

Related pages

• Debugging MCP servers in VS Code
• Debug logging for MCP servers
• Debugging stdio transport
• MCP server Vitest testing
• MCP server Zod validation