
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.
Three failure patterns
Where custom MCP servers go wrong in the first month. Hover any card to see the diagnosis.
Tool bloat
The unscoped resource
The wrong abstraction
The fix in all three: define operations before writing code, scope every list tool with a limit parameter, and separate queries from tools. These decisions are cheaper at the interface design stage than after the server is connected to a live agent.
The same-data-five-times test
The build/no-build diagnostic. Run it against any session where you suspect an MCP server would help. The test counts actual fetches, not hypothetical ones — a source that appears eight times in three sessions is a stronger candidate than one you imagine calling frequently.
Count how many times I fetch the same data
source in this session.
For each unique data source (endpoint, file, database
table, external service):
1. How many times was it fetched?
2. Were the fetch parameters the same or different?
3. What was the total token cost of the repeated
fetches (estimate: response size * occurrences)?
Then apply the MCP heuristic:
- Same source fetched 5+ times per session with
non-trivial fetch cost → MCP-worthy
- Fewer than 5, or trivial cost → shell/curl is fine
For each MCP-worthy source, list:
- The 3-5 actual operations needed (not everything
possible — the actual operations this session used)
- The minimum tool surface area to cover them
Output: a decision table. Source | Fetches | MCP-worthy? | Proposed toolsCounts fetches per data source, estimates token cost, and outputs a decision table with proposed tool surface area for MCP-worthy sources.
Most operators who run this test for the first time discover one or two sources they hadn’t noticed compounding. Shell calls are invisible in the cost sense (they don’t show on a bill) but each raw JSON response loaded into context costs tokens. A kanban source fetched eight times per session at 10KB per response is 80KB of context per session that a typed MCP response could reduce by 60-80%.
Annotated transcript
A real conversation: operator notices repeated data fetches, agent walks through the build decision, defines the tool interface, explains all three MCP primitives. Click any pinned annotation to expand the “why this turn matters” commentary.
Four operator turns, four agent turns. Result: a build decision, a five-tool interface, and a pre-build audit checklist — before a line of server code is written.
- operator
I'm noticing the agent makes 5-8 shell calls to fetch the same kanban data every session — status queries, filter by venture, check overdue items. It's slow and token-expensive. Someone suggested building an MCP server. Is that the right call here?
- agent
The signal is right. The heuristic I use: if the same data source is being fetched more than five times per session through shell or curl, and the fetch is non-trivial (auth, query construction, response parsing), that source is MCP-worthy.
Your kanban case fits. Shell calls to query tasks are:
1. Slow — shell spawn + network per call
2. Verbose in context — raw JSON responses
3. Repetitive — the same filter combinations appear across sessionsA single MCP server with 3-5 tools covers the real use cases, returns typed responses, and replaces 5-8 shell calls with 1-2 structured tool calls. Token spend drops; session latency drops.
Before building: what are the 5 things you actually need the agent to do with kanban data? List those first. That list is your tool surface area.
- operator
The five operations: (1) list tasks by venture and status, (2) get a single task with its sub-items, (3) create a task, (4) update a task's column, (5) mark a task done. That's it.
- agent
Clean. Five tools is the right surface area. Here's the shape:
list_tasks(venture?, col?, done?, limit=50) get_task(id) create_task(venture, col, title, notes?, sub_items?) move_task(id, col) complete_task(id)Three things to nail before you write a line of server code:
1. Scope the list tool.
list_tasksmust have alimitparameter and default tight — 50 is reasonable. Without it, the agent fetches everything every call.
2. Separate move from update. Moving a task to a new column is the frequent operation; general update is the infrequent one. Separate tools make the common case obvious.
3. No raw SQL through the tool interface. The tool should call a typed query layer, not accept arbitrary filter strings. Arbitrary filter strings become an injection surface and a maintenance problem.With those five tools you replace every shell-based kanban call the agent currently makes. The server is ~150 lines including the typed query layer.
- operator
What does the MCP protocol actually require? I've seen "tools, resources, prompts" mentioned but I don't know which of those I need.
- agent
For a kanban server: tools only. Here's what each primitive is for:
Tools — things the agent calls to take an action or run a query. Side effects allowed. Your five operations are all tools. This is the primitive you need.
Resources — read-only data the agent can load into context. Think: reference documents, configuration files, lookup tables. No side effects. Use when the agent needs to read a stable document, not when it needs to query live data.
Prompts — reusable prompt templates the agent or operator can invoke by name. Use when you have a multi-step prompt you want to standardize across sessions. Most servers don't need this.
For kanban: implement Tools, skip Resources and Prompts. The server schema is straightforward — each tool declares its name, description, and a JSON Schema for its arguments. The server receives a tool call, executes the query, returns a result. That's the protocol.
One practical note: the description on each tool is load-bearing. The agent reads descriptions to decide which tool to call. A vague description produces incorrect calls. Write descriptions as: what this does, when to use it, what it returns.
Minimal server checklist
A pre-ship checklist for any custom MCP server. Walk it before connecting the server to a live agent. Most interface problems are visible here; catching them at this stage is an order of magnitude cheaper than debugging incorrect tool calls in production.
MINIMAL MCP SERVER — PRE-SHIP CHECKLIST
INTERFACE DESIGN
[ ] Operations list defined BEFORE server code written
(the 3-5 actual operations, not everything possible)
[ ] Total tool count is 7 or fewer
[ ] Each tool is a verb-noun pair describing intent
(list_tasks, not get_all_items_filtered_v2)
[ ] Each list/query tool has a limit parameter
with a sensible default (<=100, never unbounded)
[ ] No raw SQL or arbitrary filter strings in any
tool argument — typed filter objects only
[ ] Read tools and write tools are clearly
distinguishable by name
DESCRIPTIONS
[ ] Each tool description states: what it does,
when to use it (vs. other tools), what it returns
[ ] Descriptions are tested: given the description
list, can you pick the correct tool for each of
your 5 operations without seeing the code?
[ ] No two tools have descriptions that could be
mistaken for each other
QUERY LAYER
[ ] Server calls a typed query layer, not raw queries
composed from tool arguments
[ ] Continuation token (or equivalent) returned when
results are truncated
[ ] Error responses include enough detail for the
agent to distinguish "not found" from "permission
denied" from "server error"
BEFORE CONNECTING TO AGENT
[ ] Validation audit run (use the third prompt in kit)
[ ] All medium and high severity issues resolved
[ ] At least one tool call tested manually with
known-good arguments
[ ] At least one tool call tested with bad arguments
(missing required field, out-of-range limit)
— confirm the error response is informative
LINE COUNT
[ ] Server is under 250 lines including validation
and typed query layer
(if over 250: interface has scope creep — re-read
the operations list and cut what isn't on it)
The description test is the one operators skip most.Read your tool descriptions as if you’re the agent — given only the names and descriptions, can you pick the right tool for each of your five operations? If you have to hesitate, the agent will too, and hesitation produces incorrect calls.
Prompt kit
Three prompts: diagnosing whether to build, designing the interface, and auditing before connecting. Save in your CLAUDE.md or a personal snippets file.
Count how many times I fetch the same data
source in this session.
For each unique data source (endpoint, file, database
table, external service):
1. How many times was it fetched?
2. Were the fetch parameters the same or different?
3. What was the total token cost of the repeated
fetches (estimate: response size * occurrences)?
Then apply the MCP heuristic:
- Same source fetched 5+ times per session with
non-trivial fetch cost → MCP-worthy
- Fewer than 5, or trivial cost → shell/curl is fine
For each MCP-worthy source, list:
- The 3-5 actual operations needed (not everything
possible — the actual operations this session used)
- The minimum tool surface area to cover them
Output: a decision table. Source | Fetches | MCP-worthy? | Proposed toolsGiven the operations list below, design a minimal
MCP tool interface.
Operations: [paste your list]
Rules:
1. Maximum 5 tools for the first version. If you
think you need more, challenge each one: can it
become an argument on an existing tool?
2. Each tool is a verb-noun pair describing intent:
list_tasks, create_task, not get_all_items_v2
3. Every list/query tool must have a limit parameter
with a sensible default (<=100)
4. No raw SQL or arbitrary filter strings in the
interface — use a typed filter object
5. Write the description for each tool as if the
agent must pick the right one from a list. Vague
descriptions produce wrong calls.
Output:
- Tool name + signature (TypeScript-style)
- One-sentence description per tool
- The field that would most commonly be wrong and whyAudit this MCP server before I connect it to the agent.
Paste the server's tool definitions (names,
descriptions, argument schemas).
Check:
1. TOOL COUNT: Are there more than 7 tools? If so,
which can be merged via structured arguments?
2. DESCRIPTIONS: Is each description specific enough
that the agent can distinguish between similar
tools? Flag any that are ambiguous.
3. LIST TOOLS: Do all list/query tools have an
explicit limit parameter? What's the default?
Could a miscall return unbounded data?
4. ABSTRACTION LEVEL: Are any tools at the wrong
level? (individual queries as tools, rather than
one query tool with filter arguments)
5. SIDE EFFECTS: Are read tools and write tools
clearly named differently? Can a read be mistaken
for a write?
Output: a risk table — Tool | Issue | Severity (low/med/high) | FixApply this — build one server the right way
~2-hour exercise.Diagnose, design, build, audit. Don’t connect until the checklist is clean.
Your first minimal MCP server
Each step takes 15-30 minutes. Progress saves automatically.
- 01Run the same-data-five-times test against your last three sessions. Identify the top candidate for an MCP server.Use the first prompt in the kit. Count actual fetches, not hypothetical ones. A source that appears 8 times in three sessions is a stronger candidate than one you imagine calling frequently.
- 02For the top candidate, write the operations list — the 5 actual things the agent needs to do with that data. Stop at 5.Not what's possible — what was actually used in the sessions you reviewed. The list should fit in a sentence each. If an operation takes a paragraph to describe, it's two operations.
- 03Draft the tool interface using the second prompt in the kit. Run the validation audit on your own draft before writing any server code.Most interface problems are visible before implementation. A 15-minute audit on the interface spec catches issues that would otherwise cost two days of debugging incorrect tool calls.
- 04Build the minimal server. Target: fewer than 200 lines including argument validation and typed query layer. Verify each tool description is unambiguous.If the server is growing past 200 lines in the first version, the interface has scope creep. Re-read the operations list and cut what isn't on it.
- 05Run the validation audit prompt on the finished server. Fix anything rated medium or high severity before connecting to the agent.High-severity issues (unbounded list tools, ambiguous descriptions, wrong abstraction level) produce incorrect agent behavior that's hard to debug once the server is live. Fix them at the interface layer.