How to Build Your First MCP Server in Node.js

November 7, 2026

An MCP server is a small program that exposes tools, resources, or prompts to an AI client through the Model Context Protocol, a JSON-RPC 2.0 based spec. A minimal Node.js server with two tools is about 40 lines using the official SDK, and the client config that loads it is five lines of JSON.

The protocol solves a real problem: every client used a different way to add capabilities. MCP makes one server work in Claude Desktop, Cursor, VS Code, and anything else that speaks it.

What does an MCP server actually expose?

Three primitives, each with a different purpose:

  • Tools — functions the model can call, with JSON-schema inputs. Side effects allowed.
  • Resources — read-only data addressed by URI, like file:///notes/today.md.
  • Prompts — reusable prompt templates the user can select in the client.

Most servers only need tools. Resources make sense for document stores; prompts are for workflows the user starts deliberately.

Transport-wise there are two options: stdio for local servers the client launches as a subprocess, and HTTP with server-sent events for remote ones. Start with stdio — it needs no networking, no auth, and no deployment.

How do you build a server with two tools?

  1. npm init -y && npm i @modelcontextprotocol/sdk zod
  2. Create server.js:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

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

server.tool(
  "search_notes",
  "Search local markdown notes by keyword",
  { query: z.string(), limit: z.number().min(1).max(20).default(5) },
  async ({ query, limit }) => ({
    content: [{ type: "text", text: `Found ${limit} notes matching ${query}` }],
  })
);

server.tool(
  "count_words",
  "Count words in a text block",
  { text: z.string() },
  async ({ text }) => ({
    content: [{ type: "text", text: String(text.split(/\s+/).length) }],
  })
);

await server.connect(new StdioServerTransport());
  1. Add "type": "module" to package.json and run node server.js to confirm it starts without crashing.

Two details that trip people up. Tool descriptions are how the model decides when to use a tool — write them like documentation, not labels. And stdio servers must never write to stdout except protocol messages; use console.error for logs.

How do you connect the server to a client?

Claude Desktop: open claude_desktop_config.json and add an entry.

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"]
    }
  }
}

Use the absolute path. Relative paths resolve against the client’s working directory, which is rarely what you expect. On macOS the config lives at ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%\Claude\claude_desktop_config.json.

Restart the client fully — closing the window is not enough on macOS. Then check the tools icon to confirm both tools appear.

What are the security rules worth following from day one?

A stdio MCP server runs with your user permissions and no sandbox. Four rules:

  • Never trust tool arguments. Validate with the schema, then validate again in the handler for anything touching the filesystem.
  • Whitelist paths. A read_file tool that accepts any path lets a prompt-injected page read your SSH keys.
  • No shell passthrough. If a tool runs commands, build argv arrays, not shell strings.
  • Log to stderr. Anything on stdout corrupts the protocol stream and produces confusing client errors.

Prompt injection is the live threat. A tool that fetches web content and returns it to the model can be made to run other tools by a malicious page. Treat tool output as untrusted input.

Where does MCP stop being useful?

For one client and one tool, an MCP server is more setup than a function call. The payoff starts at two clients or two tools.

Stdio servers also cannot be shared. If three people need the tool, you need an HTTP server with auth, which is a different project — tokens, rate limits, and multi-tenant isolation.

The spec is still moving. Servers built six months ago may need small changes; pin your SDK version and read the changelog before upgrading.

Good fit: developers adding private data access to an assistant, teams standardizing tool access across multiple AI clients.

Poor fit: single-client scripts, anything needing fine-grained audit trails (the protocol does not give you that), and teams without a place to run a persistent process.

Quick Summary

  • An MCP server exposes tools, resources, and prompts over JSON-RPC; stdio transport is the simplest start.
  • Two tools fit in roughly 40 lines with the official Node SDK and zod schemas.
  • Use absolute paths in client configs and restart the client completely.
  • Never log to stdout — it corrupts the protocol stream.
  • Validate every tool argument and whitelist filesystem paths; treat tool output as untrusted.
Tags: