Building MCP Servers in TypeScript That Don't Fall Apart

Your MCP server works great at tool number three. By tool number twelve it is a pile of switch cases you are afraid to touch. Here is the TypeScript architecture that keeps it clean as it grows — borrowed straight from Domain-Driven Design.

The Problem with Flat MCP Servers

Most MCP server tutorials start with something like this:

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

const server = new Server(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    { name: "get_user", description: "\"Get a user by ID\", inputSchema: { ... } },"
    { name: "create_order", description: "\"Create an order\", inputSchema: { ... } },"
    { name: "send_email", description: "\"Send an email\", inputSchema: { ... } },"
    { name: "get_product", description: "\"Get product details\", inputSchema: { ... } },"
    // ...8 more tools
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  switch (request.params.name) {
    case "get_user": return handleGetUser(request.params.arguments);
    case "create_order": return handleCreateOrder(request.params.arguments);
    case "send_email": return handleSendEmail(request.params.arguments);
    // ...
  }
});

Familiar? The problem is not that this code is wrong. It is that it scales to exactly one person maintaining it for exactly three weeks.

Once you hit real production requirements — different owners for user logic vs order logic, different auth contexts, stateful resources — you need structure. That is where Domain-Driven Design earns its keep.

Three DDD Concepts, One MCP Mapping

You do not need to read a 600 page book to apply the ideas that matter here. Three concepts cover 90% of what you will encounter:

DDD Concept	What it means	MCP equivalent
Bounded context	A namespace where terms have a consistent meaning	Tool name prefix (`users__get`, `orders__create`)
Aggregate root	The single entry point for a cluster of related state	A typed server context object passed to each handler
Domain event	A fact that happened in the system	An MCP notification emitted after a mutation

The translation rule for this niche: never write an "architecture" article — write a TypeScript tutorial that teaches architecture through code. So let us build the thing.

Bounded Contexts as Tool Namespaces

In DDD, a bounded context is a boundary within which a particular domain model applies. In an MCP server, that maps cleanly to a tool naming convention plus a factory function that groups related tools together.

Here is a createDomainTools factory:

// src/domains/types.ts

import { Tool, CallToolResult } from "@modelcontextprotocol/sdk/types.js";

export interface DomainTool<TInput = unknown> {
  definition: Tool;
  handler: (input: TInput) => Promise<CallToolResult>;
}

export interface DomainModule {
  namespace: string;
  tools: DomainTool[];
}

export function createDomainModule(
  namespace: string,
  tools: DomainTool[]
): DomainModule {
  return {
    namespace,
    tools: tools.map((tool) => ({
      ...tool,
      definition: {
        ...tool.definition,
        name: `${namespace}__${tool.definition.name}`,
      },
    })),
  };
}

Now define the users domain:

// src/domains/users.ts

import { createDomainModule } from "./types.js";

export const usersDomain = createDomainModule("users", [
  {
    definition: {
      name: "get",
      description: "Get a user by ID",
      inputSchema: {
        type: "object",
        properties: {
          id: { type: "string", description: "User UUID" },
        },
        required: ["id"],
      },
    },
    handler: async ({ id }: { id: string }) => {
      const user = await db.users.findById(id);
      return {
        content: [{ type: "text", text: JSON.stringify(user) }],
      };
    },
  },
  {
    definition: {
      name: "list",
      description: "List users with optional filters",
      inputSchema: {
        type: "object",
        properties: {
          limit: { type: "number" },
          role: { type: "string" },
        },
      },
    },
    handler: async ({ limit = 20, role }: { limit?: number; role?: string }) => {
      const users = await db.users.findMany({ limit, role });
      return {
        content: [{ type: "text", text: JSON.stringify(users) }],
      };
    },
  },
]);

The resulting tool names are users__get and users__list. The double underscore is a common MCP convention for namespacing — it is readable and easy to split on in client code.

I cover the agent design patterns that consume these namespaced tools in my multi-agent design patterns post — the namespace boundary maps directly to the "agent as specialist" pattern.

Aggregate Root for Server State

The aggregate root is the single class responsible for coordinating all writes to a domain's state. In an MCP server, "state" usually means cached data, auth tokens, connection pools, or feature flags that multiple tools share.

The anti-pattern: each handler closes over a different reference to the same underlying data, and you end up with stale reads mid-session.

The fix is a typed ServerContext that every handler receives as an injected dependency:

// src/context.ts

export interface UserContext {
  currentUserId: string | null;
  permissions: Set<string>;
  refresh: () => Promise<void>;
}

export interface ServerContext {
  users: UserContext;
  requestId: string;
  startedAt: number;
}

export function createServerContext(): ServerContext {
  const users: UserContext = {
    currentUserId: null,
    permissions: new Set(),
    async refresh() {
      const session = await auth.getCurrentSession();
      this.currentUserId = session?.userId ?? null;
      this.permissions = new Set(session?.permissions ?? []);
    },
  };

  return {
    users,
    requestId: crypto.randomUUID(),
    startedAt: Date.now(),
  };
}

Then update the DomainTool interface to carry context:

export interface DomainTool<TInput = unknown> {
  definition: Tool;
  handler: (input: TInput, ctx: ServerContext) => Promise<CallToolResult>;
}

Now each handler has a type safe path to shared state with no globals:

handler: async ({ id }: { id: string }, ctx: ServerContext) => {
  if (!ctx.users.permissions.has("users:read")) {
    return {
      content: [{ type: "text", text: "Forbidden" }],
      isError: true,
    };
  }
  const user = await db.users.findById(id);
  return { content: [{ type: "text", text: JSON.stringify(user) }] };
},

A stateful MCP server is also an injection surface worth thinking about carefully. I cover the specific attack patterns you should harden against in my post on prompt injection hardening for agents.

Domain Events as MCP Notifications

Domain events record facts that have happened ("OrderPlaced", "UserCreated"). MCP has a notification mechanism that maps naturally to this pattern.

Here is a typed notification emitter that the publisher can subscribe to:

// src/events.ts

import { Server } from "@modelcontextprotocol/sdk/server/index.js";

type EventName =
  | "users.created"
  | "orders.placed"
  | "orders.failed";

interface DomainEvent<TData = unknown> {
  name: EventName;
  data: TData;
  occurredAt: number;
}

export function createEventEmitter(server: Server) {
  return {
    async emit<TData>(name: EventName, data: TData): Promise<void> {
      const event: DomainEvent<TData> = {
        name,
        data,
        occurredAt: Date.now(),
      };

      // MCP notification — any connected client sees this
      await server.notification({
        method: "notifications/message",
        params: {
          level: "info",
          logger: name,
          data: JSON.stringify(event),
        },
      });
    },
  };
}

Use it inside a handler after a successful mutation:

handler: async ({ email, role }: CreateUserInput, ctx: ServerContext) => {
  const user = await db.users.create({ email, role });

  await events.emit("users.created", { userId: user.id, email });

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

The client (your AI agent or IDE) now receives a realtime notification whenever a user is created — without polling. For testing these notification paths, the evaluation patterns I describe in evaluating LLM agents in production apply directly: set up an observer client, trigger the mutation, assert the notification fired within your SLA window.

Wiring It All Together

Here is a complete server.ts that composes the domain modules, context, and events:

// src/server.ts

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  ListToolsRequestSchema,
  CallToolRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

import { createServerContext } from "./context.js";
import { createEventEmitter } from "./events.js";
import { usersDomain } from "./domains/users.js";
import { ordersDomain } from "./domains/orders.js";

const server = new Server(
  { name: "my-structured-server", version: "1.0.0" },
  { capabilities: { tools: {}, logging: {} } }
);

const events = createEventEmitter(server);
const domains = [usersDomain, ordersDomain];

// Flat list of all tool definitions across all domains
const allTools = domains.flatMap((d) =>
  d.tools.map((t) => t.definition)
);

// Lookup map: tool name → handler
const handlerMap = new Map(
  domains.flatMap((d) =>
    d.tools.map((t) => [t.definition.name, t.handler])
  )
);

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: allTools,
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const ctx = createServerContext();
  await ctx.users.refresh();

  const handler = handlerMap.get(request.params.name);
  if (!handler) {
    return {
      content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
      isError: true,
    };
  }

  return handler(request.params.arguments ?? {}, ctx);
});

const transport = new StdioServerTransport();
await server.connect(transport);

The handlerMap lookup is O(1). Adding a new domain means writing one file and adding one import — the server.ts does not change.

Is This Overkill?

For three tools? Yes. For a server that a team will ship, maintain, and extend over six months? No.

The patterns here add about 40 lines of infrastructure. In exchange you get: namespaced tools that cannot collide, a single typed context object instead of scattered globals, and notifications that fire without wiring up polling clients.

If you are not sure whether your use case actually needs an MCP server or a simpler agent framework, the AI agent framework chooser on my site walks through the decision.

If you want a deeper look at how stateful MCP servers fit into larger agent architectures, I cover it in more detail on my site.

If you want this wired up on your own production system end to end, that is exactly the kind of work I take on.

Drop a comment if your setup looks different — curious what variations people are running in production.

推荐订阅源

DEV Community