Build an MCP Server in 30 Minutes: A Step-by-Step Tutorial

Every coding assistant and agent you have used recently probably consumed tools over the Model Context Protocol (MCP). Building your own MCP server is the fastest way to expose your service to every AI client at once, instead of writing one integration per assistant. This tutorial builds a real, working server in about 30 minutes — no prior MCP experience required.

The example we will build is a weather-and-time server written in TypeScript with the official @modelcontextprotocol/sdk. It exposes three tools: one returns the current time, one forecasts weather for a city, and one converts temperatures. You will finish with a server you can test, debug, and wire into a desktop or remote client.

What you need before you start

• Node.js 20 or newer installed locally.
• npm or your preferred package manager.
• An MCP-capable client for testing: Claude Desktop, a recent VS Code build, or the official mcp-inspector tool via npx @modelcontextprotocol/inspector.

Project setup

1. Create a directory and initialize it with npm init -y, then set the package to module type in package.json.
2. Install the SDK and schema library: npm install @modelcontextprotocol/sdk zod.
3. Create a src/server.ts file and add a minimal TypeScript config (target ES2022, module NodeNext).

Declaring tools with zod schemas

The SDK exposes a server object whose tool() method takes a name, a description, and a Zod schema describing the arguments. The description matters more than you think: the model uses it to decide when to call the tool and how to fill in the arguments, so write it the way you would document a public API for a human. A vague description means the model calls your tool at the wrong time with the wrong inputs.

stdio vs HTTP: choosing a transport

The transport is how clients reach your server. stdio spawns the server as a child process and talks over stdin and stdout — ideal for local desktop tools where the user already runs your binary. HTTP (the newer stateless transport) exposes the server over the network, so many clients and users can connect to a single running instance. Local tool? Use stdio. Shared service? Use HTTP. The SDK keeps the transport pluggable, so you can support both with a few lines of wiring.

• stdio: zero network surface and simplest to debug, but one server process per client.
• HTTP: one server serves many clients and deploys behind a load balancer, but you must handle authentication and rate limiting.
• Start with stdio during development, then switch to HTTP for deployment without rewriting your tool logic.

Testing your server without a client

Before wiring in a full assistant, drive the server directly. The inspector gives you a GUI to list tools, call them with crafted arguments, and inspect the raw JSON-RPC traffic. Add a small script that connects over stdio, calls each tool with edge-case inputs (an empty city, missing arguments), and asserts the result shape — this catches schema mistakes before any model ever sees your tool.

Deploying for remote clients

1. Build a single bundled entry point (esbuild or tsc) so the HTTP transport starts cleanly in production.
2. Run behind a TLS-terminating proxy and add an API-key check in a middleware wrapper.
3. Set a generous request timeout — a hanging tool call stalls the entire assistant conversation.
4. Monitor tool latency and failure rates from day one; a broken tool silently degrades every client that calls it.

FAQ