TL;DR: Install the official TypeScript SDK (@modelcontextprotocol/server) and zod, register one tool with registerTool, start it with serveStdio, build it, and point Claude Code or Claude Desktop at the compiled file. Test it with the MCP Inspector before you connect any client. The finished server below is about 40 lines.
Here’s how to build an MCP server in short: you write a small program that lists the tools it offers (a name, a description and an input schema) and answers calls from an AI client. The official SDKs handle the protocol for you. In TypeScript that means one McpServer instance, one registerTool call per tool, and serveStdio to talk to the client.
At AIO Software, clients now ask for an MCP server next to the REST API almost as a default. Most of them need two or three tools, not twenty. So this guide builds one tiny, useful server: a check_url tool that fetches a URL and reports its HTTP status and response time. You can ask Claude “is the staging site up?” and it calls your code. You need Node.js 20 or newer and a client such as Claude Code.
One warning about older tutorials: the TypeScript SDK moved to v2 in July 2026, alongside the 2026-07-28 spec. Many guides still import from @modelcontextprotocol/sdk, the v1 package. New projects should start on v2. Everything below follows the official build-server guide and the TypeScript SDK README as of October 2026.
How to build an MCP server in 5 steps
1. Set up the project
mkdir site-check && cd site-check
npm init -y
npm install @modelcontextprotocol/server zod
npm install -D @types/node typescript
mkdir src
Then add "type": "module" and a build script to package.json, and create a tsconfig.json. These are trimmed from the official quickstart:
// package.json (add these keys)
"type": "module",
"scripts": { "build": "tsc" }
// tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"types": ["node"],
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"skipLibCheck": true
},
"include": ["src/**/*"]
}
2. Write the tool
Create src/index.ts. The server lives inside a createServer() function because serveStdio calls it whenever it needs a fresh instance (more on that in step 3).
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";
function createServer() {
const server = new McpServer({ name: "site-check", version: "1.0.0" });
server.registerTool(
"check_url",
{
description: "Fetch a URL and report its HTTP status code and response time",
inputSchema: z.object({
url: z.string().url().describe("Full URL, including https://"),
}),
},
async ({ url }) => {
const started = Date.now();
try {
const res = await fetch(url, { signal: AbortSignal.timeout(10000) });
const ms = Date.now() - started;
return {
content: [{ type: "text", text: `${url} returned ${res.status} in ${ms} ms` }],
};
} catch (error) {
return {
content: [{ type: "text", text: `Could not reach ${url}: ${String(error)}` }],
isError: true,
};
}
},
);
return server;
}
serveStdio(createServer, {
onerror: (error) => console.error("site-check error:", error),
});
console.error("site-check MCP server running on stdio");
The description matters more than people expect, because the model reads it to decide when to call your tool. The zod schema becomes the JSON Schema the client sees. Returning isError: true tells the model the call failed without crashing the server.
3. Serve it over stdio and build
The last three lines are the transport. According to the official docs, serveStdio negotiates the protocol version with each client, so the same server answers new 2026-07-28 clients and older ones that still use the 2025-era handshake. The older pattern, server.connect(new StdioServerTransport()), still compiles, but it only serves 2025-era clients.
Notice the logging goes to console.error. On a stdio server, stdout carries the JSON-RPC messages, and a stray console.log corrupts them. This is the bug I see most often in client code. Now run npm run build.
4. Test it with the MCP Inspector
npx @modelcontextprotocol/inspector --cli node build/index.js --protocol-era modern --method tools/list
You should see check_url with its schema. Run it again with --protocol-era legacy (the Inspector’s default) and both should list the tool. Debugging here is much faster than inside a chat client.
5. Connect it to Claude Code or Claude Desktop
In Claude Code, the -- separates Claude’s options from the command that starts your server (see the Claude Code MCP docs):
claude mcp add site-check -- node /ABSOLUTE/PATH/site-check/build/index.js
Start a session, type /mcp to confirm the server is connected, and ask “check https://example.com”. For Claude Desktop, add the same command to claude_desktop_config.json and restart the app. Cursor and most other clients accept the same mcpServers block:
{
"mcpServers": {
"site-check": {
"command": "node",
"args": ["/ABSOLUTE/PATH/site-check/build/index.js"]
}
}
}
Prefer Python? The official Python SDK does the same with less code. You create MCPServer("site-check") from mcp.server, put @mcp.tool() on a typed async function with a docstring, and finish with mcp.run(transport="stdio"). Type hints become the schema.
When you need a remote server instead
Stdio is right for anything on the user’s own machine. Once other people or a hosted agent need the server, switch to the Streamable HTTP transport, put it behind HTTPS and add OAuth. The v2 SDK has helper packages for Express, Fastify and Hono, so the tool code stays the same. Most of your time goes on auth and rate limits.
A real example: SchedPilot, a social media scheduler built for AI agents, runs a hosted MCP server with six tools (get_accounts, list_posts, create_post, upload_media, delete_post, get_analytics). Posts an agent creates land in the calendar for a human to approve before anything goes out. That approval step is worth copying. I compared more servers like it in social media tools with MCP servers, and the background on why this matters is in how AI assistants are learning to run social accounts.
Mistakes that break MCP servers
- Writing to stdout. Use
console.erroror a logger that writes to stderr or a file. - Relative paths in client config. Use absolute paths.
- Forgetting to rebuild. The client runs
build/index.js, not your TypeScript. - Ten overlapping, vaguely named tools. Three clear ones work better.
- Write tools with no approval step for anything that deletes, sends or publishes.
My opinion: wrap an API you already have instead of designing a new one for the model. With a clean REST API (see what good developer APIs look like), your MCP tools become thin wrappers and you keep one set of business logic.
Where to go from here
Get the local version working with one tool, test it in the Inspector, then add tools one at a time. Move to HTTP only when someone other than you needs access. If you want an MCP server and API built for your product, or an agent that uses them, that’s work my agency does: talk to AIO Software. For ideas on what agents can automate once connected, see the AI automation tools I’d pick and schedulers that work with Claude and ChatGPT.
FAQ
How long does it take to build an MCP server?
A local stdio server with one or two tools takes an hour or less with the official SDK. A remote server with OAuth, logging and rate limits is a few days of real engineering work.
Should I build an MCP server in Python or TypeScript?
Use the language your existing backend is in. Both official SDKs support tools, resources and prompts. Python needs less boilerplate, and TypeScript fits teams already running Node.
Is @modelcontextprotocol/sdk still the right package?
Not for new projects. It is the v1 package. The v2 SDK, released in July 2026, splits into @modelcontextprotocol/server and @modelcontextprotocol/client, and v1 gets fixes for at least six months after that release.
Why does my MCP server connect and then immediately fail?
Usually something is printing to stdout, which corrupts the JSON-RPC stream on a stdio server. Move all logging to stderr, rebuild, and test again with the MCP Inspector.