7.7
Build A Custom MCP
Why this exists
Existing connectors cover the big services. They don't cover your systems — the internal thing, the odd API, the database with your own shape of question in it.
This is also the lesson where "I can't code" stops being true in any way that matters. You're going to build a working piece of software today, and you won't write it. You'll specify it, read it, test it and fix it — which, as 2.5 said, was always the actual job.
The idea
An MCP server is a small program that says: here are the four things Claude may do, and here's what comes back.
You're not building a service. The service already exists. You're building the counter in front of it — deciding which operations are available and what shape the answers take.
Which means the design work is subtraction, and it's the part that matters:
| Decide | Example |
|---|---|
| What operations exist | "Get bookings for a date range." Not "query the database." |
| What each returns | Five fields you need. Not the forty the API has. |
| What it cannot do | Read only. No writes. Ever. |
Start read-only. Everything from 6.3 applies with more force here, because this thing will run unattended once it exists. A server that can only read cannot cause the quiet, invisible damage that took a whole lesson to warn you about. Add writing later, deliberately, if you ever genuinely need it.
Narrow beats general. The instinct is to expose everything so it's flexible. Resist it — a server with four well-shaped operations is more useful than one that can do anything, because Claude picks correctly from four and flounders across forty. And a narrow surface is one you can reason about when something goes wrong.
Local first. Runs on your machine, nobody else can reach it, and you can break it freely. Hosting it so a team can use it is a real thing you might want later and it's a different job with different risks.
The build is a conversation: describe what you want, let it write it, read what it wrote, run it, fix what's broken. Every skill from Levels 5 and 6 applies — plan mode, read the diff, prove it works, commit each step. This is the first time you'll use all of them at once on something that didn't exist before.
Do
- Pick something you'd genuinely use. A question you ask a system repeatedly and answer by hand.
- Write the design before building — three things: - The operations (aim for two to four) - What each returns (name the exact fields) - What it cannot do (start with: no writes)
- Give the design to Claude and ask it to build a local, read-only MCP server. Plan mode on.
- Read the plan before approving.
- Build it. Commit as you go, per 5.2.
- It won't work first time. Read the error yourself first, per 6.2, before pasting it anywhere.
- Get it running and connect it.
- Use it for the real question it was built for.
- Verify the answer independently — the same second-source check from 6.3.
- Write
my-mcp.md: what it does · the operations · what it can't do · what broke and how you found it.
Step 9 matters. A server you built returning a confident wrong number is a new way to be wrong, and it's one you'd trust more than you should because you made it.
Done when
Never do
Never give a custom server write access on its first version. It runs unattended. Unattended writing is how the invisible failures from 6.3 happen, with nobody in the room.
Never expose more operations than you need. Every extra one is surface area you have to reason about at the worst possible moment.
Never skip verifying its output because you built it. Your own tool is the one you'll trust most and check least.