Skip to content
SearchSubscribe
Expert · Lesson 09 — Building your first custom MCP server
E09Expert
Expert · Lesson 09● live

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.

20 min read · 2 hours applyprereq: Operating 04 (hooks)

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.

SignalBuild?Why
Same source, 5+ fetches/session, non-trivial fetchYesShell overhead compounds; typed responses reduce token cost
Community server already exists for this sourceUse existingMaintenance cost is not yours; interface is already validated
Fetch is trivial (<5 calls/session, single-line curl)NoShell is cheaper than the build cost at this volume
Data shape changes frequentlyWaitSchema 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.

PrimitiveWhat it isWhen to use it
ToolsFunctions 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.
ResourcesRead-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.
PromptsReusable 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.

№ 01

Tool bloat

claim looks like“A team exposes every database operation as its own MCP tool: get_task, update_task, delete_task, list_tasks_by_status, list_tasks_by_venture, archive_task, restore_task... 30 tools in the first month. The agent starts guessing which tool to call and combining them incorrectly.”
what’s missingThe tool surface area has grown past what the agent can reason about reliably. Each additional tool increases the combinatorial space the agent must navigate to produce a correct call sequence. The design goal should be the minimum set of tools that covers the real use cases — not a 1:1 mapping from database rows to operations.
the moveStart with 3-5 tools. One broad read tool that takes structured filter arguments beats six narrow read tools. Ask: what are the 5 actual things the agent needs to do? Design to those. Add tools only when a real use case can't be served by an existing tool with richer arguments.
№ 02

The unscoped resource

claim looks like“A resource endpoint returns the entire project history — every task, every note, every log entry since day one. 50MB per call. Works fine in testing. In production, the agent calls it on every session start to "stay oriented" and token spend triples overnight.”
what’s missingResources need explicit scope bounds. "Return everything" is not a resource design — it's a database dump. The agent will use whatever you give it; if the resource returns 50MB, the agent loads 50MB into context and charges accordingly.
the moveResources should return the minimum slice useful for the agent's current task. Add a required scope parameter: time window, venture filter, status filter, limit. Default to a tight window (last 30 days, limit 50). Return a continuation token if the caller needs more. Never return unbounded data.
№ 03

The wrong abstraction

claim looks like“Every query the agent might want to run is exposed as a separate tool: get_overdue_tasks, get_tasks_assigned_to_ceo, get_tasks_created_this_week, get_high_priority_tasks. New filter combinations generate new tool requests. The server becomes a request queue for one-off tools.”
what’s missingThe abstraction layer is at the wrong level. Individual queries are not tools — they're arguments. The tool is "query tasks"; the query parameters are the arguments. Exposing every query as a separate tool conflates the interface with the implementation and produces a server that's perpetually incomplete.
the moveOne tool, structured arguments. `query_tasks(filters: { status?, venture?, priority?, due_before?, due_after?, limit? })` handles every combination the previous seven tools covered. The server stays stable; new filter needs become argument additions, not tool additions.

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.

The same-data-five-times test
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 tools

Counts 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.

Deciding to build a custom MCP server

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.

  1. 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?

  2. 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 sessions

    A 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.

  3. 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.

  4. 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_tasks must have a limit parameter 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.

  5. 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.

  6. 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.

The same-data-five-times test
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 tools
Draft a minimal MCP tool interface
Given 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 why
Validate an MCP server before connecting it to the agent
Audit 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) | Fix

Apply 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.

0/5
  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
Expert tier · what's next

After this lesson