Building Your First MCP Server: From Concept to Connected Tool in a Day

The first MCP server I built took three days because I spent most of that time reading the specification and trying to understand what was actually necessary versus what was optional boilerplate. The second one took a few hours. By the fifth, the pattern was so clear that new servers were a half-day project. This guide is everything I wish I had known before day one.

What an MCP Server Actually Does

An MCP server is a process that exposes capabilities (tools, resources, and prompts) over a standardised protocol that any MCP-compatible host can use. The server does not care which AI model is on the other side — Claude, GPT-4o, or an open-source model running locally. As long as the host is MCP-compatible, your server works with it.

The server communicates over stdio (for local tools) or HTTP with Server-Sent Events (for remote tools accessible over the network). Most initial MCP servers use stdio — it is simpler and sufficient for tools running on the same machine as the AI host.

The Three Primitives in Practice

Tools are functions the model can call. Define them with a name the model will use to invoke them, a description that helps the model understand when to use the tool (this description is critical — write it as if explaining to a smart assistant, not a developer), and a JSON Schema describing the parameters. When the model decides to call your tool, the host sends a tool call request to your server, your server executes the function, and returns the result.

Resources are URI-addressable read-only data. Think of them as the file system or database that the model can read. Resources are surfaced to the model as available context it can pull in when needed. A database MCP server might expose each table as a resource. A file system server exposes directory listings and file contents as resources.

Prompts are named prompt templates that users can invoke by name in the host interface. They let you pre-build useful workflows — a "summarise project" prompt or a "code review" prompt — that combine tools and resources in a useful sequence.

Building a Simple File System MCP Server

The canonical starting point is a file system server. It exposes tools for reading files, listing directories, and writing files — simple operations that are immediately useful and cover the core patterns.

Using the Python MCP SDK (available via pip), the structure is: import the SDK, create a server instance, define your tools with the tool decorator, define resource handlers if needed, and run the server. Each tool function receives the parameters the model passes and returns a result. The SDK handles the protocol framing, serialisation, and connection management.

The most important thing to get right early: your tool descriptions. The model uses the description to decide whether to call the tool and with what parameters. A vague description produces wrong tool calls. A specific, action-oriented description ("reads the complete contents of a text file at the given path and returns them as a string") produces correct ones. Spend more time on descriptions than on implementation.

Testing and Deploying

Claude Desktop has native MCP support and is the fastest way to test a local server. Add your server to the Claude Desktop config file, restart the application, and your tools appear in the model's available capabilities. Test by describing what you want Claude to do in natural language — a working server should result in the model calling your tool correctly without you specifying the tool name.

For production deployment, the considerations are: authentication (MCP does not standardise auth — implement it on your server), rate limiting, logging, and monitoring. Treat your MCP server like any other microservice: deploy it with health checks, structured logging, and alerting on error rates. An MCP server that fails silently is worse than a broken integration because the model may continue attempting to use the tool without knowing it is broken.