How to Build an MCP Server in TypeScript (Part 1): Setup and Tool Design

This is Part 1 of a three-part NextFlows Academy reference for building a Model Context Protocol (MCP) server in TypeScript. In six weeks you go from “what is MCP?” to a public GitHub repo with real tools, Zod validation, docs, and a Demo Day presentation — the same path used in the free Building an MCP for an AI Engine cohort.

Part 1 covers Weeks 1–2: environment setup, your first tool, MCP Inspector, project selection, tool design, Zod schemas, and a multi-tool skeleton. Continue with Part 2: data and security and Part 3: test, docs, and ship.

Stack for this course: Node.js 20+, TypeScript via tsx, the official MCP TypeScript SDK, Zod for input schemas, and MCP Inspector for local testing. Prefer stdio transport for local demos in Claude Desktop or Cursor.

This guide is written for 4th- and 5th-year Computer Science and Computer Engineering students, and for self-learners with basic programming experience who want a shipped MCP — not only theory.

You do not need prior GitHub expertise. Week 1 starts from creating an account, a repository, and a first commit. You do need about a few focused hours per week for six weeks, plus live sessions if you join the cohort (Wednesday and Saturday online 1:30–3:30 PM, and Monday on-site 9:00 AM–5:00 PM on kickoff, code-review, and Demo Day weeks).

By the end of Week 1 you should have a public GitHub repository, a TypeScript MCP server with one working tool, and a screenshot or short recording of MCP Inspector listing and calling that tool.

Official references to keep open: the MCP documentation, the MCP specification, and the TypeScript SDK guide Build your first server.

Step 1 — Learn the mental model. MCP connects AI hosts (Claude, Cursor, and others) to servers you write. Servers expose tools (actions), resources (read-only context), and prompts. Your job in this course is to ship tools the model can call safely.

Step 2 — Set up GitHub. Create an account if needed, create a public repo for the whole cohort, make a first commit with a README, and push it. Follow GitHub Hello World if this is new.

Step 3 — Install the toolchain. Install Node.js 20+, confirm `node -v` and `npm -v`, and install your editor (Cursor or VS Code). You will run TypeScript with `tsx` so you can avoid a heavy build step early on.

Step 4 — Scaffold the server. Initialize an npm project with `"type": "module"`, install the cohort-pinned MCP SDK packages plus `zod` and `tsx`, and create `src/index.ts` that registers one tool (for example `greet` or `echo`) with a Zod `inputSchema`.

Step 5 — Serve over stdio. Hand the server to the SDK’s stdio entry so the host speaks MCP on stdin/stdout. Log only to stderr — stdout is reserved for the protocol.

Step 6 — Call it with Inspector. Run Inspector against your start command (typically something like `npx @modelcontextprotocol/inspector npx tsx src/index.ts`). List tools, call with valid args, then call with invalid args and confirm schema validation rejects bad input.

Step 7 — Submit Week 1 evidence. Mandatory evidence in the academy: GitHub repo URL + first commit; a short written explanation of tools vs resources vs prompts; Inspector proof that your first tool works.

Zod is a TypeScript library that defines the shape of data and checks it at runtime. For MCP tools, Zod (or an equivalent schema) becomes your `inputSchema`: the contract the host and model see, and the validator that runs before your handler.

You use Zod so invalid arguments fail safely, so every field can carry a `.describe(...)` hint for the model, and so one schema drives both runtime checks and TypeScript types. That pattern matches how the MCP TypeScript SDK registers tools.

Week 2 is design-first. You pick a starter project, write a mentor-ready design doc, define Zod schemas for your P0 tools, register a multi-tool skeleton, and prove every tool appears in Inspector — even if handlers still return stubs.

Starter project options used in the academy: Notes & FAQ Search, Personal Expense Tracker, To-Do List, Weather Briefing, and Quote of the Day. Advanced ideas (repo health, course planner, job tracker) need mentor approval before you expand scope.

Step 1 — Branch. From your Week 1 main branch, create `week-2-design`.

Step 2 — Pick one idea. Score starters on interest, offline demoability, no paid API keys, and fit in four remaining build weeks. Write one sentence in `docs/project-choice.md`: “I am building X for Y so that Z.”

Step 3 — Learn tool design rules. One job per tool; verb_noun names (`search_notes`, `add_expense`); descriptions written for the model; prefer small focused tools over mega-tools with an `action` enum.

Step 4 — Write `docs/design.md` (mandatory). Include pitch, Demo Day user story, a tool inventory table (4–7 tools with inputs/outputs), mark exactly three tools as P0, list out-of-scope items, success criteria, and top risks. Open a GitHub Issue for mentor review before Week 3.

Step 5 — Add Zod schemas (mandatory). Create schemas for at least three P0 tools under `src/schemas/`. Every field needs `.describe(...)`. Handlers may still be stubs.

Step 6 — Register the skeleton. Structure the repo as `src/index.ts`, `src/tools/`, `src/schemas/`, `examples/`, and `docs/`. Register every inventory tool; stubs can return JSON with `{ stub: true }`.

Step 7 — Inspector + examples (mandatory). Add `examples/<tool_name>.json` for each tool. Confirm Inspector lists all tools, accepts valid samples, and rejects bad input. Attach screenshots to your design Issue.

Step 8 — Definition of done. Project choice filed, design approved (or pending with Issue link), ≥3 schemas, server starts cleanly, examples present, branch pushed.

Keep a layout mentors can review quickly: `src/index.ts` (server + transport), `src/tools/*.ts` (one register helper per tool), `src/schemas/` (Zod contracts), `examples/` (sample JSON args), `docs/design.md`, and `docs/project-choice.md`.

This structure lets Week 3 replace stubs with data loaders without rewriting registration or schemas.

Logging to stdout and breaking stdio transport. Use `console.error` for debug logs.

Vague tool names and descriptions that the model cannot select reliably.

Skipping the design doc and coding seven tools with no Demo Day story.

Schemas without `.describe(...)`, so the model guesses argument meaning.

Choosing a paid API or OAuth-heavy project in Week 2 — save that for after you ship.

Next: How to Build an MCP Server, Part 2 — Connect Data and Harden Security (Weeks 3–4). Then finish with Part 3 — Test, Document, and Ship on Demo Day (Weeks 5–6).

Apply to the free cohort or follow along self-paced from the academy application page. For protocol depth, stay aligned with modelcontextprotocol.io/docs.