Building your first custom MCP server
When to build vs. use existing. The protocol in plain language. The failure modes that cost teams two weeks each.
When to build vs. use existing
The Model Context Protocol (MCP) is a standard for giving agents structured access to tools, data sources, and prompt templates. Hundreds of community servers already exist — databases, APIs, file systems, calendars. The first question isn’t how to build a server. It’s whether to build one at all.
The heuristic: if the agent is fetching the same data source more than five times per session through shell calls or curl, and each fetch is non-trivial (authentication, query construction, response parsing), that source is MCP-worthy. Below five fetches, or where the fetch is a single-line curl with no auth, shell is fine.
The five-times threshold isn’t arbitrary. It’s the crossover point where the cost of building and maintaining a server (initial build, schema updates, deployment) is recovered in token savings and session latency within a month of operation. Below five, the math rarely works out.
| Signal | Build? | Why |
|---|---|---|
| Same source, 5+ fetches/session, non-trivial fetch | Yes | Shell overhead compounds; typed responses reduce token cost |
| Community server already exists for this source | Use existing | Maintenance cost is not yours; interface is already validated |
| Fetch is trivial (<5 calls/session, single-line curl) | No | Shell is cheaper than the build cost at this volume |
| Data shape changes frequently | Wait | Schema churn makes server maintenance expensive; stabilize first |
One other gate: check the community registry before building. Unofficial MCP server collections exist for most common data sources. Building a custom PostgreSQL connector when a maintained community version exists is a maintenance liability, not an asset.
Three protocol primitives
MCP exposes three first-class concepts. Most servers only need one of them.
| Primitive | What it is | When to use it |
|---|---|---|
| Tools | Functions the agent can call. Side effects allowed. The agent selects and calls a tool; the server executes and returns a result. | Any operation or query against a live data source. This is the primitive most servers need. |
| Resources | Read-only data the agent loads into context. No side effects. Think reference documents, configuration files, lookup tables. | Stable documents the agent needs to read but not modify. Avoid for live data — use a Tool instead. |
| Prompts | Reusable prompt templates the agent or operator invokes by name. Parameterized and versioned server-side. | Multi-step prompts you want consistent across sessions and operators. Most servers don’t need this. |
For most custom servers: implement Tools only. Resources add complexity for marginal benefit when the same data can be returned by a read-only Tool. Prompts are useful at scale across teams; for a single operator with a single project, CLAUDE.md handles the same problem with less infrastructure.
The tool schema is straightforward: each tool declares a name, a natural-language description, and a JSON Schema for its arguments. The description is load-bearing — the agent reads it to decide which tool to call. Ambiguous descriptions produce wrong calls. Write descriptions as: what this does, when to use it (not the others), what it returns.
The rest of Expert · Lesson 09 is for subscribers.
Building your first custom MCP server
- Every Expert-tier lesson — diagnostic prompts, transcripts, prompt kits, full homework
- Every research paper — methodology, figures, tables, reproducibility appendices
- New Expert lessons + papers as they ship (quarterly cadence)
- Foundations + Operating lessons stay free; bundles on GitHub stay free; this tier is the deep stuff
Free while the early catalog ships. Paid tier comes later — subscribe now and you’re grandfathered in.