Build an MCP Server in Node.js & TypeScript: A Practical HazelJS Tutorial

Expose your existing TypeScript classes to Cursor, Claude Desktop, and any other Model Context Protocol (MCP) client — without writing protocol code, without a heavy SDK, and without standing up a separate HTTP service.

This post walks through the hazeljs-mcp-starter example in this folder: a small but realistic task board MCP server, written in TypeScript, that you can run locally with node dist/main.js and immediately drop into your AI tooling. It is not another "hello world" — every pattern below is the same one you would use to ship an internal support agent, a runbook automation server, or an admin operations panel for your team.

By the end you will know:

• What MCP actually is (and is not), at the wire level
• Why a tiny abstraction like @hazeljs/mcp beats writing JSON-RPC by hand
• How to define tools with @Tool() decorators in idiomatic TypeScript
• How to wire the resulting server into Cursor and Claude Desktop
• How to test it without an LLM in the loop
• How to evolve from in-memory toy code to a production-grade tool server (validation, persistence, observability, security)

Source code: hazel-js/hazeljs-mcp-starter on GitHub. Clone it and follow along:

git clone [e-mail]:hazel-js/hazeljs-mcp-starter.git
cd hazeljs-mcp-starter
npm install

---

1. What is the Model Context Protocol, really?

MCP is a small, open JSON-RPC 2.0 protocol for one job: letting an AI client (Cursor, Claude Desktop, an SDK, your own runner) discover and invoke tools and resources exposed by a server. The wire format is intentionally boring — newline-delimited JSON over stdio (or HTTP/SSE) — which is what makes it portable.

The methods you'll see in practice are:

Method	Direction	Purpose
initialize	client → server	Handshake; server returns name, version, capabilities
ping	either	Liveness check
tools/list	client → server	Server returns its tool catalog (with JSON Schema)
tools/call	client → server	Server runs a named tool with arguments

A tool, on the wire, is just a name + description + JSON Schema for inputs. When the model decides to call it, the client sends tools/call, the server runs the corresponding function, and the result comes back as a content block (typically { type: 'text', text: '...' }).

That is the entire surface area. Everything else — auth, persistence, validation, observability — is your application's job, exactly as it would be for any other JSON-RPC service. MCP is plumbing, not a framework.

Why the protocol is small (and why that matters)

Because MCP is so minimal, the same server that Cursor talks to today can be consumed tomorrow by Claude Desktop, an OpenAI client, your in-house agent runtime, or a bash one-liner. You write the business logic once and let the transport carry it. That is the central value proposition we'll lean on for the rest of the article.

---

2. Why use @hazeljs/mcp instead of writing the protocol by hand?

Spec-correct JSON-RPC + MCP is not hard, but it's repetitive: parsing newline-delimited frames, routing methods, mapping your domain types to JSON Schema, formatting error envelopes with the right code values, preserving this context across decorator-based handlers, and so on. @hazeljs/mcp does all of that in roughly 200 lines, with zero runtime dependencies, so you can drop it into any Node.js project without dragging in a transport SDK or an LLM client.

Concretely, the package gives you three pieces:

1. HazelToolAdapter — a transport-agnostic adapter that maps Hazel-style ToolMetadata (what @Tool() produces) to MCP's McpToolDefinition and dispatches tools/call to the right method, with the original this binding intact.
2. A request router — pure async function over McpRequest → McpResponse, easy to plug into stdio (provided), HTTP, or SSE.
3. A stdio transport — listenStdio() wires the router to process.stdin / process.stdout and handles concurrent in-flight calls without head-of-line blocking.

It also pairs with @hazeljs/agent, which provides the @Tool() decorator and ToolRegistry. The registry is the same one Hazel agents use internally, so a tool you write for your agent is automatically MCP-ready without a second tool definition format.

If you already have a ToolRegistry running inside your agent, you do not need to redefine anything. The same registry instance can be passed to createMcpServer() to project that tool surface to MCP clients.

---

3. What the starter does (and why a task board?)

A task board has just enough domain logic to be non-trivial: state, IDs, validation, status transitions, filtering. Replace the in-memory store with Prisma, Redis, or your HTTP API and the MCP boundary stays identical. That is the lesson worth taking home.

The starter exposes four tools:

Tool	Inputs	Output	Purpose
list_tasks	status? ("open"/"done")	{ tasks: Task[] }	List all tasks; optional status filter
add_task	title (string)	Task	Create a new open task
complete_task	task_id (string)	Task	Transition a task to done
board_stats	(none)	{ open: number, done: number }	Quick aggregate for the model

Implementation files (linked to GitHub):

• src/agents/TaskBoardMcpAgent.ts — domain logic + @Tool() decorators
• src/main.ts — registry + createMcpServer() + listenStdio()
• tsconfig.json — TypeScript config (notably experimentalDecorators: true)
• package.json — pinned npm versions of @hazeljs/agent and @hazeljs/mcp

---

4. Project layout

hazeljs-mcp-starter/
├── package.json
├── tsconfig.json
├── README.md
├── BLOG.md                ← you are here
└── src/
    ├── main.ts            ← MCP entrypoint
    └── agents/
        └── TaskBoardMcpAgent.ts

A few things to notice:

• Single TypeScript project, single output directory. No monorepo gymnastics; tsc -p tsconfig.json writes everything to dist/.
• src/main.ts is intentionally tiny. All it does is build the registry, hand it to createMcpServer, and call listenStdio(). Tests should drive the agent class directly, not the transport.
• No top-level reflect-metadata import. @Tool() does not need design-time type metadata; only experimentalDecorators is required. Keeping that out of the surface keeps the bundle tiny.

---

5. The agent class, decorator by decorator

Here is the heart of the starter. Each method has a one-to-one mapping to an MCP tool, with parameter metadata that becomes JSON Schema in tools/list.

import { Tool } from '@hazeljs/agent';

type TaskStatus = 'open' | 'done';

interface Task {
  id: string;
  title: string;
  status: TaskStatus;
  createdAt: string;
}

/**
 * In-memory task board exposed as MCP tools.
 * Replace the store with Prisma, Redis, or your API — the @Tool surface stays the same.
 */
export class TaskBoardMcpAgent {
  private tasks: Task[] = [];
  private nextId = 1;

  @Tool({
    name: 'list_tasks',
    description: 'List tasks. Optionally filter by status (open or done).',
    parameters: [
      {
        name: 'status',
        type: 'string',
        description: 'Optional filter: "open" or "done"',
        required: false,
      },
    ],
  })
  async listTasks(input: Record<string, unknown>): Promise<{ tasks: Task[] }> {
    const filter = typeof input.status === 'string' ? input.status.toLowerCase() : undefined;
    const tasks =
      filter === 'open' || filter === 'done'
        ? this.tasks.filter((t) => t.status === filter)
        : [...this.tasks];
    return { tasks };
  }

Full file on GitHub: src/agents/TaskBoardMcpAgent.ts

A few design choices worth explaining:

name is decoupled from the method name. listTasks (camelCase) is your TypeScript ergonomics; list_tasks (snake_case) is what the model sees. Keep the model-facing names short, lowercase, and verb-led — they show up in tool palettes and prompts.

description is prompt engineering. The LLM uses descriptions to decide whether to call your tool. "List tasks. Optionally filter by status" is much more useful than "List tasks." Add expected formats and edge cases ("Returns an empty array when no tasks exist"), but stay terse. A long description bloats every tool-routing prompt.

Parameters become a JSON Schema object. Each entry maps directly to a property under inputSchema.properties, with required: true lifting the name into inputSchema.required. Optional fields are declared as required: false and omitted from the required list. The model receives the full schema in tools/list and constructs valid arguments.

Inputs are Record<string, unknown>, not typed at compile time. That is the trade-off of working with an LLM: you cannot trust the shape, you must validate at runtime. We do exactly that with typeof input.status === 'string'. For larger tools, switch to a runtime validator (zod, ajv, valibot) — the package supports schema on @Tool() for Zod-first definitions.

Errors are thrown. When add_task receives an empty title we throw, and the MCP transport converts the exception into a -32603 INTERNAL_ERROR JSON-RPC response. The client surfaces that to the model, which can then retry with a corrected payload. For expected validation failures consider returning { ok: false, error: '...' } instead — that lets you keep HTTP-style semantics in the JSON body and avoids polluting your error logs.

---

6. The entrypoint: from class to wire

src/main.ts is deliberately five lines of "real" work:

/**
 * MCP entrypoint — started by Cursor / Claude Desktop via STDIO.
 * Build first: npm run build → run dist/main.js
 */
import { ToolRegistry } from '@hazeljs/agent';
import { createMcpServer } from '@hazeljs/mcp';

import { TaskBoardMcpAgent } from './agents/TaskBoardMcpAgent';

const registry = new ToolRegistry();
registry.registerAgentTools('taskboard', new TaskBoardMcpAgent());

const server = createMcpServer({
  name: 'hazeljs-mcp-starter-taskboard',
  version: '1.0.0',
  toolRegistry: registry,
});

server.listenStdio();

What happens, step by step:

1. new ToolRegistry() creates an empty store of name → ToolMetadata.
2. registerAgentTools('taskboard', new TaskBoardMcpAgent()) reads decorator metadata off the class, creates fully-qualified entries (taskboard.list_tasks, …) for agent-to-agent dispatch, and keeps the short name ("list_tasks") that MCP clients will see.
3. createMcpServer(...) snapshots the registry into a HazelToolAdapter, builds the JSON-RPC router, and returns an object with listenStdio() and listTools().
4. server.listenStdio() attaches the router to process.stdin / process.stdout using a line-buffered reader. From this point forward, the process is a long-lived MCP child.

A subtle point: the registry is snapshotted at server-create time. If you add tools after createMcpServer() they will not show up. That is by design — MCP supports a listChanged capability for dynamic catalogs, but most servers do not need it, and a stable snapshot keeps the adapter simple.

---

7. The wire protocol, end to end

For an add_task call the conversation looks like this (one JSON object per line, both directions):

Client → server: handshake

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}

Server → client

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverInfo":{"name":"hazeljs-mcp-starter-taskboard","version":"1.0.0"},"capabilities":{"tools":{}}}}

Client → server: discover tools

{"jsonrpc":"2.0","id":2,"method":"tools/list"}

Server → client (truncated)

{"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"add_task","description":"Create a new open task with the given title.","inputSchema":{"type":"object","properties":{"title":{"type":"string","description":"Short description of the work item"}},"required":["title"]}}, …]}}

Client → server: call a tool

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add_task","arguments":{"title":"Buy milk"}}}

Server → client

{"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"{\"id\":\"tsk_1\",\"title\":\"Buy milk\",\"status\":\"open\",\"createdAt\":\"2026-05-09T16:49:51.862Z\"}"}],"isError":false}}

Heads up: MCP is JSON-RPC, not a CLI. Typing bare commands like list_tasks into the running server's stdin returns -32700 Parse error — that is the spec correctly rejecting non-JSON input, not a bug.

If you want a friendly REPL on top of these tools, build it as a separate script that consumes the registry directly. The MCP server itself must remain protocol-pure so real clients can talk to it.

---

8. Running the starter

Clone the hazel-js/hazeljs-mcp-starter repository and install:

git clone [e-mail]:hazel-js/hazeljs-mcp-starter.git
cd hazeljs-mcp-starter
npm install
npm run build

You should now have dist/main.js. To run it standalone (it will block on stdin, which is normal):

node dist/main.js

To exercise the protocol without typing JSON by hand, paste these envelopes one per line into the running server's stdin and press Enter after each:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"add_task","arguments":{"title":"Buy milk"}}}
{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"list_tasks","arguments":{}}}
{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"board_stats","arguments":{}}}

That's the fastest feedback loop for "did my change break the protocol?" — much faster than a full Cursor reload.

The repository's package.json pins published versions of the HazelJS packages:

"@hazeljs/agent": "0.7.9",
"@hazeljs/mcp": "0.7.9"

---

9. Wiring Cursor

Add a server entry to .cursor/mcp.json at your project root, with an absolute path to the built dist/main.js. Relative paths sometimes work, but absolute is unambiguous across reloads:

{
  "mcpServers": {
    "hazeljs-taskboard": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/hazeljs-mcp-starter/dist/main.js"]
    }
  }
}

Reload the MCP servers (or restart Cursor). The four tools should appear in the tool list, and the model can call them in chat. A natural prompt to try:

"Add a task titled 'Write MCP blog' and another 'Ship starter repo', mark the first one done, then show me board stats."

If something goes wrong, Cursor surfaces the JSON-RPC error code in its MCP logs. -32601 (method not found) usually means the server crashed and a different process is responding; -32603 (internal error) means a tool threw — log the exception in the server to see the real cause.

---

10. Wiring Claude Desktop (macOS)

In ~/Library/Application Support/Claude/claude_desktop_config.json, add the same command / args pair pointing at your dist/main.js. Restart Claude Desktop. Tool discovery happens automatically on next chat.

The same dist/main.js works for both Cursor and Claude Desktop because MCP is a contract, not a vendor protocol. That's the whole point.

---

11. From in-memory to production

The starter's array store is a placeholder; here are the swap-ins you will actually want.

Persistence with Prisma

import { PrismaClient } from '@prisma/client';

export class TaskBoardMcpAgent {
  constructor(private prisma: PrismaClient) {}

  @Tool({ name: 'add_task', description: 'Create a new open task', parameters: [
    { name: 'title', type: 'string', description: 'Title', required: true },
  ]})
  async addTask(input: { title: string }) {
    return this.prisma.task.create({
      data: { title: input.title.trim(), status: 'open' },
    });
  }
}

Construct the agent with a PrismaClient once in main.ts; every tools/call reuses the connection pool.

Distributed state with Redis

For multi-process deployments where any worker can serve any call (e.g. a managed agent platform spinning up several MCP children), back the store with Redis. @Tool() doesn't change. The methods just become thin wrappers over redis.hSet / hGetAll.

Calling existing HTTP APIs

The most common path: your tools wrap existing REST or gRPC endpoints. Pass an httpClient (axios, undici, fetch) into the constructor and translate domain calls inside each @Tool(). This is typically the first MCP server a team ships — it gives the model read/write access to systems that are already running, without touching the underlying services.

Schema-first validation with Zod

For anything beyond toy tools, declare a Zod schema instead of a parameters[] array:

import { z } from 'zod';

const AddTaskInput = z.object({
  title: z.string().min(1).max(280),
  priority: z.enum(['low', 'medium', 'high']).default('medium'),
});

@Tool({
  name: 'add_task',
  description: 'Create a new open task',
  schema: AddTaskInput,
})
async addTask(input: z.infer<typeof AddTaskInput>) { ... }

@hazeljs/agent converts the Zod schema to JSON Schema for tools/list and (with guardrails enabled) validates inputs before your method runs. You get autocomplete inside the method body and reject malformed inputs at the boundary, not deep inside business logic.

---

12. Error handling without surprises

There are two failure modes worth thinking about:

Programmer errors (bugs) should throw. The transport will return a -32603 INTERNAL_ERROR envelope, the client logs it, and you see a stack trace in stderr. Do not catch and swallow these.

User-facing failures (validation, "not found", "already completed") should return a structured result instead of throwing. Example:

async completeTask(input: { task_id: string }) {
  const task = this.tasks.find((t) => t.id === input.task_id);
  if (!task) {
    return { ok: false, error: `No task with id: ${input.task_id}` };
  }
  task.status = 'done';
  return { ok: true, task };
}

The model sees a normal JSON response and can recover gracefully (e.g. ask the user to confirm the ID). Reserve thrown exceptions for "this should never happen" cases.

For protocol-level errors (-32700, -32601, -32602) you don't write any code — the package generates the right envelope automatically.

---

13. Multi-agent registries

Real systems split tools across domains. You can register multiple agents into the same registry:

const registry = new ToolRegistry();
registry.registerAgentTools('support', new SupportAgent(deps));
registry.registerAgentTools('billing', new BillingAgent(deps));
registry.registerAgentTools('admin', new AdminAgent(deps));

const server = createMcpServer({ name: 'company-tools', version: '1.0.0', toolRegistry: registry });
server.listenStdio();

Tool names must be globally unique at the MCP layer because the adapter keys by short name. Either pick distinct name values (e.g. support_lookup_customer vs billing_lookup_customer) or run separate processes per domain. The latter is often cleaner: it gives you per-domain logging, restart blast-radius, and access controls.

---

14. Security: what to check before shipping

MCP servers run as child processes of trusted clients, so the threat model is different from a public HTTP API — but it is not zero.

• Treat tool inputs as untrusted. The model can be prompt-injected by an upstream document, page, or message, and forwarded inputs reflect that. Validate, escape, and bound everything you pass to your data layer (no raw SQL string-interpolation, no eval, no shell exec without an allowlist).
• Don't log secrets. Tools often pass through API keys or PII. Strip secrets from winston / pino events. Hazel's logger supports redaction patterns; use them.
• Bound destructive actions behind requiresApproval. @hazeljs/agent lets you mark tools that should pause for human approval. Use it for password resets, refunds, deletes — anything you would not want a model to do unattended.
• Pin tool names. Renaming a tool can silently degrade an agent that learned to call it. If you must rename, alias the old name for a deprecation window.

---

15. Observability

Because the server is "just Node.js," any logger or metrics backend you already use works:

• Logs: wrap the agent with a Proxy (or a @hazeljs/agent middleware) that logs tool_name, duration_ms, and is_error for every call. Five lines of code, enormous debugging value.
• Metrics: export a counter mcp_tool_calls_total{tool, status} and a histogram mcp_tool_duration_seconds{tool}. Cursor will happily call your tools 10× per chat — you want a graph for that.
• Tracing: start a span around each tools/call invocation and propagate it into downstream HTTP/db calls. OpenTelemetry's @opentelemetry/instrumentation-http covers most of it for free.

A nice property of MCP: because every interesting action is a tools/call, you get per-tool telemetry without any framework opinionation — just instrument the adapter once.

---

16. Comparing alternatives

Approach	Pros	Cons
Hand-written MCP server (no SDK)	Full control, zero deps	You re-implement JSON-RPC framing, error envelopes, JSON Schema mapping
Official MCP TypeScript SDK	Officially maintained, full feature set (resources, prompts, sampling)	Heavier, separate tool definition style; less idiomatic if you already use Hazel decorators
@hazeljs/mcp + @hazeljs/agent	Single tool definition shared with your agent runtime, ~200-line transport, no deps	Tool-only today (resources/prompts not yet covered)
Custom HTTP API consumed by an agent	Familiar mental model, easy to test	Every IDE / client needs a bespoke integration; not portable
OpenAI-only function calling	First-class in OpenAI clients	Single-vendor; requires your code to be the orchestrator instead of the IDE

For most teams already running TypeScript backends, @hazeljs/mcp hits the sweet spot: write your tools once with @Tool(), expose them to every MCP client today, and migrate to the official SDK later if you need resources/prompts/sampling.

---

17. Where to go next

• Replace the in-memory store with your real data layer (Prisma, Drizzle, MongoDB, or an HTTP client over your existing services).
• Add a domain-specific server for each subsystem (support, billing, infra) and register them under separate .cursor/mcp.json entries — one process per blast-radius.
• Adopt Zod schemas with @Tool({ schema }) for validated inputs and inferred TypeScript types in the method body.
• Wire approvals with requiresApproval: true on destructive tools and configure your client to gate them.
• Layer observability (logs + metrics + traces) at the adapter level, not inside each tool.
• Read the package source — @hazeljs/mcp on GitHub is small enough to read in 15 minutes and understanding it makes debugging trivial.

The combination of @Tool() and @hazeljs/mcp keeps the server's surface area small: one decorator per method, one registry, one createMcpServer, one line to listen. Your domain logic stays domain logic, the protocol stays plumbing, and any MCP-aware client picks up your tools for free.

---

References

• Starter source on GitHub: hazel-js/hazeljs-mcp-starter
• HazelJS @hazeljs/mcp on npm
• HazelJS @hazeljs/agent on npm
• Model Context Protocol specification
• JSON-RPC 2.0