Building Custom MCP Servers: A Complete Guide

Building an MCP server that works in demo is easy. Building one that works in production requires attention to authentication, error handling, rate limiting, and deployment. This guide covers everything from initial setup to running your server at scale.

Project Setup

Start with the official MCP TypeScript SDK. Initialize a new project with TypeScript, add the @modelcontextprotocol/sdk package, and create your server entry point. The SDK provides a Server class that handles protocol negotiation and message routing. You register tool handlers, resource handlers, and prompt handlers on this class.

Designing Your Tool Interface

Good tool design is crucial for AI usability. Each tool should do one thing well. Use descriptive names (search_documents, not search). Write detailed descriptions that explain what the tool does, when to use it, and what it returns. Define input schemas with clear property names, descriptions, and validation constraints. The AI uses these descriptions to decide when and how to call your tools.

Error Handling

MCP defines structured error responses with error codes and messages. Map your internal errors to appropriate MCP error codes: InvalidParams for bad input, InternalError for server failures, and custom error codes for domain-specific issues. Always include actionable error messages — the AI will relay these to the user, so messages like connection timeout, retrying is more useful than error code 504.

Authentication and Authorization

For servers that access user data, implement OAuth 2.0 or API key authentication. The MCP transport layer supports passing authentication tokens in the initial connection handshake. Validate tokens on every request and scope tool access based on the authenticated user permissions. Never expose admin-only tools to regular users.

Deployment Options

MCP servers can run as local processes (stdio transport), HTTP servers (SSE or WebSocket transport), or serverless functions. For personal use, stdio with Claude Desktop is simplest. For team use, deploy as an HTTP server behind authentication. For public distribution, package as an npm module that users install and run locally. Document your deployment options clearly in your README.