How to Build an MCP Server in 2026 — What You Need to Know Before You Start
The Model Context Protocol (MCP) is how you give Claude direct access to your business systems — databases, CRMs, internal tools, APIs. Instead of copying data into prompts, Claude connects through a server you build and control.
The MCP SDK has hit 97 million monthly downloads. The ecosystem is exploding. But most developers building their first MCP server make the same expensive mistakes we did.
We published our own MCP server on npm. It runs in production managing 31 service trucks. Here's what we wish someone had told us before we started.
What an MCP Server Actually Does
An MCP server exposes "tools" that Claude can call. Think of it like building an API, but instead of human users calling your endpoints, an AI agent does. The server handles the connection, validates inputs, executes the tool logic, and returns results.
A simple MCP server has three layers:
- Transport layer — How Claude connects (stdio for local, HTTP for remote)
- Tool registry — What Claude can do (each tool has a name, description, and schema)
- Handler logic — What actually happens when a tool is called
That's the basics. Here's where it gets interesting — and where most people get burned.
The 5 Architecture Decisions That Matter
Building a "hello world" MCP server takes 20 minutes. Building one that works in production takes weeks — unless you know what decisions to make upfront.
1. Transport: Stdio vs HTTP
Stdio is simpler and works great with Claude Desktop. HTTP is required for remote deployments and multi-user setups. Most tutorials only show stdio. If you're building for a team or deploying to the cloud, you need HTTP — and that brings auth, CORS, and connection management into play.
2. Authentication
The MCP SDK doesn't include auth. At all. If your server touches anything sensitive (and it probably does — that's the whole point), you need to build auth yourself. API keys are the minimum. JWT tokens are better for multi-user setups. We've seen servers deployed with zero auth that exposed entire databases to anyone who connected.
3. Rate Limiting
Claude agents can make hundreds of tool calls per minute. Without rate limiting, a single runaway session can overwhelm your backend, spike your API costs, or take down a database. We learned this the hard way — $1,100 in one afternoon.
4. Error Handling
An unhandled exception in a tool handler kills the entire MCP server. That means Claude loses connection mid-task. Your agent dies. Any work in progress is lost. Every tool handler needs try/catch, typed errors, and graceful degradation.
5. Schema Validation
Claude will occasionally send malformed inputs to your tools. If you're not validating with something like Zod, you'll get silent failures or worse — your tool executes with bad data and corrupts something downstream.
What a Production MCP Server Actually Needs
Here's the full stack we run in production. Most tutorials cover the first two. The rest is what separates a demo from a real system:
- TypeScript server with
@modelcontextprotocol/sdk - Tool registry with Zod schema validation
- Authentication middleware (API key + JWT)
- Per-client rate limiting
- Structured JSON logging
- Typed error classes with proper error codes
- Environment configuration management
- Docker deployment config
- Railway and Fly.io deployment configs
- Test setup with Vitest
- Claude Desktop integration config
- Full documentation for adding new tools
Building all of this from scratch took us about 3 weeks of iteration. Most of that time was spent on the non-obvious stuff — auth edge cases, rate limiting tuning, error recovery patterns, and deployment config that actually works across platforms.
🔒 Skip the 3 weeks of trial and error
The MCP Starter Kit is the exact production architecture we run. TypeScript server, auth middleware, rate limiting, deployment configs for Docker/Railway/Fly, full test setup, and documentation for adding your own tools. Ship your first MCP server in hours, not weeks.
Get the MCP Starter Kit — $199 →Includes: Complete TypeScript server, auth middleware, rate limiting, Zod validation, Docker + Railway + Fly configs, Vitest tests, 4 documentation guides
Quick Win: Test If MCP Is Right For You
Before building anything, ask yourself: does Claude need to ACCESS your systems, or just KNOW ABOUT them? If Claude just needs context (your business rules, your processes, your preferences), a workspace setup with CLAUDE.md is simpler and cheaper. MCP servers are for when Claude needs to read from or write to your actual systems in real time.
If the answer is "yes, Claude needs live access," then you need an MCP server. The question is whether you spend 3 weeks building one from scratch, or start with a production-tested foundation.