How to create MCP servers for Claude Code
Personal software is the biggest productivity unlock of 2026
Picture this. You’re at your kid’s football match on a Saturday morning.
A question hits you — what’s actually moving on EU AI regulation this week?
You pull out your phone, open the Claude app, and tell Claude Code:
“Research the state of EU AI regulation this week.”
Then you put the phone away and watch the match.
Five things happen next:
Claude Code on your laptop wakes up and reads the request.
It recognizes a research routine you’ve written for yourself and starts following it.
The routine calls your custom research tool, which asks Perplexity for a web-grounded answer with sources.
The tool returns a structured summary with citations.
Claude formats it the way you like to read it, emails the report to your inbox, and signs off.
After the lemonade break, a finished research report is waiting for you.
Every piece of that workflow is available today, and it’s easier to set up than you might think. The phone-to-laptop tunnel (Claude Code’s remote control), the routine (Claude Skills), the email tool, the orchestration — all real, all working.
TLDR: A custom MCP server is the smallest, most personal piece of software you’ll build this year — sixty lines of Python that nobody else in the world has, built in an hour by talking to Claude Code, and reshaped every time you reach for it.
The piece that turns a generic AI assistant into one that knows your work is the custom web research tool. And that’s what we’re building today.
Software for one
What you’re about to build is a piece of “personal software.”
Built for one person — you. Runs on one machine — yours.
Doing one job well enough that you’ll keep using it.
This is not how most software works.
SaaS apps are built for the average customer. They bend slowly, on someone else’s roadmap, and never quite around your workflow. That’s why you’re always copying things between applications using Excel — because spreadsheets do bend.
But spreadsheets are also brittle, untraceable, and they can’t reach outside themselves to call a service or read your inbox.
This is where MCP servers come in.
They run on your laptop.
They give your AI agents exactly the abilities you wished it had.
And they are infinitely malleable.
The first time you find a sharper edge in your work, you talk to Claude Code and the tool changes shape in two minutes. No support ticket. No roadmap meeting.
Done pulling action items from your Granola meeting notes manually?
A computer agent can do it for you, if you give it access to the right tools.
Tired of spending countless hours researching and drafting cold outreach emails?
So was I, so I built a system that does it for me.
Still clicking through your CRM like a madcap? Let Claude handle it.
When I wrote The Era of Disposable Software back in January, the framing was that software is becoming N=1 — built for one person, used for one job, sometimes thrown away after. A custom MCP server is the cleanest, smallest expression of that idea you can hold in your hands today.
What we’re building
A small program that runs on your laptop and gives Claude one new ability: ask Perplexity a question, get back a research summary with citations.
About sixty lines of code. You won’t write any of it. You’re going to ask Claude Code to write it for you. The only things you need to do yourself are install two pieces of software (we’ll walk through it together), get one API key, and tell Claude Code what you want.
Once it works, any time you ask Claude to “research X” it will use this tool to do the real research and weave the result into whatever it’s doing.
That’s the goal.
A tool nobody else in the world has, built in an afternoon, useful right away.
Three words you’re going to keep seeing
Before we get going, three terms need some clarification — because the names are confusing and they look like the same thing.
A Skill is a text file that teaches Claude how to do something. Instructions are in plain English, no code. These are the automations computer agents run on — they encode your process knowledge and knowhow.
An MCP server is a small software program that gives Claude something new it can do — call an outside service, update your CRM, send an email. Skills are instructions. MCP servers are the tools your computer agents use to interact with the world around them. Still confused? I wrote an entire post about it earlier this year.
A plugin is a way to bundle Skills and MCP servers together with hooks and slash commands so you can share them with someone else.
Today we’re building an MCP server. We’ll wrap a Skill around it at the end.
Before you start
Most readers should install before they build.
Granola, Notion, Slack, your CRM — most of the tools you already pay for publish official MCP servers. Maintained by the people who made the original product, vetted, and free. Try those for a couple of weeks before you build your own.
Most “I wish Claude could do X” wishes are already covered by official MCP servers.
Build your own only when no maintained server fits the shape of your workflow.
Once you’ve done it once, creating another server is a twenty-minute job.
Want a finished template instead? I published a few free MCP server templates as part of my AI Operating System hub — including a 5-tool Perplexity research server (Python, an extended version of what we’re building today) and a LinkedIn Carousel generator (TypeScript). Copy and go.
What you’ll need. A laptop running macOS or Windows. Claude Code already installed and working — if not, Claude Code for non-coders is the post that walks you through that. And finally, a Perplexity API key.
An “API key” is just a private password that lets your software program ask Perplexity questions on your behalf. The free tier covers light use; if you go through it heavily, you’re paying fractions of a cent per question.
Step 1 — Open your terminal and install uv
Everything we’re about to do happens in a window called the terminal — a text-based way to talk directly to your computer. On macOS, hit Cmd + Space, type “Terminal”, press Enter. On Windows, search for “PowerShell” in the Start menu and open it.
You’ll see a black or white box with a blinking cursor.
Don’t worry about what’s inside. We’re going to paste two things into it.
First, install uv. uv is a single tool that handles everything Python-related for you: it installs Python, manages packages, and keeps each project tidily in its own sandbox so they don’t interfere with one another. Paste this in (Mac):
curl -LsSf https://astral.sh/uv/install.sh | shOn Windows PowerShell, use this instead:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Press Enter. uv will download itself, install in a folder on your computer, and tell you when it’s done. About ten seconds.
Once uv is installed, have it install Python for you:
uv python install 3.12That’s it. You now have a clean Python you didn’t have to think about and that won’t fight anything else on your machine. From this point on, you’ll never need to think about Python versions again — uv takes care of that.
Step 2 — Make a folder for your new tool
Pick a place on your computer where you keep work — your Documents folder, a Projects folder, wherever. I personally prefer to create dedicated MCP servers for different projects (“AI workspaces”), so I’m going to nest the folder with MCP servers in this AI workspace folder.
Read this post if you have no idea what I mean with an “AI workspace”.
So for a “research” workspace, I would create the research folder and a subfolder called mcp-servers:
mkdir -p ~/Projects/research/mcp-servers
cd ~/Projects/researchThe first line creates the folder. The second moves your terminal into your research AI workspace directory (cd is short for “change directory”).
All the commands that follow will affect this folder, and only this workspace directory.
Step 3 — Get your Perplexity key
Open perplexity.ai/settings/api in your browser, sign in, and create a new API key. It will start with pplx-. Copy it.
Keep it somewhere safe for a minute — your password manager is best.
Don’t paste it into a chat with anyone, including Claude.
A leaked API key can rack up real charges on your account before you notice.
We’ll set up a safe place for it in the next step.
Step 4 — Tell Claude Code to build the server for you
From inside the research workspace folder you just created, start Claude Code:
claudeWhen it’s ready, paste in this prompt:
“Build me a custom MCP server in Python for Claude Code in mcp-servers/web-research. It should expose one tool called
web_researchthat takes aqueryargument, calls Perplexity’ssonar-proAPI, and returns the answer with citations. Use the uv workflow, FastMCP, stdio transport. Read the API key from a.envfile in this folder. Initialize the project withuv init, thenuv addthe packages you need. Add a.gitignorethat keeps.envout of git. Don’t run the server yet — I want to add my API key first and review the code.”
Claude Code will think for a few seconds and then create four files in ~/Projects/research/mcp-servers/web-research:
pyproject.toml— the list of things this project needs to runserver.py— the actual program (the sixty lines we keep mentioning).env.example— a template showing what secrets the program expects.gitignore— a list of files git should ignore, including.env
You don’t have to follow every line, but it’s worth seeing the shape of what was built:
import os
from pathlib import Path
import httpx
from dotenv import load_dotenv
from mcp.server.fastmcp import FastMCP
load_dotenv(Path(__file__).parent / ".env")
PERPLEXITY_API_KEY = os.getenv("PERPLEXITY_API_KEY")
if not PERPLEXITY_API_KEY:
raise RuntimeError("PERPLEXITY_API_KEY not set. Add it to .env in this folder.")
mcp = FastMCP("research")
@mcp.tool()
async def web_research(query: str, focus: str = "balanced") -> str:
"""Run a web-grounded research query and return a summary with citations.
Args:
query: The research question. Be specific — "EU AI Act enforcement
updates in May 2026" works better than "EU AI Act".
focus: One of "balanced", "technical", "business", "recent".
"""
# ... calls Perplexity, parses the answer, returns text + citations
if __name__ == "__main__":
mcp.run(transport="stdio")The thing worth noticing: the function called web_research has a plain-English description at the top (“Run a web-grounded research query and return a summary with citations…”).
That description is the most important part of the entire file.
It’s what Claude reads when deciding whether or not to use this tool. “Run a web-grounded research query and return a summary with citations” is specific enough that Claude knows when to reach for it; “do research” would not be.
Now create a real .env file (not the example one) in the same folder.
The leading dot is intentional — it tells your operating system to keep it hidden from casual browsing. The easiest way: stay in the terminal and type:
echo "PERPLEXITY_API_KEY=pplx-your-actual-key-here" > .envReplace pplx-your-actual-key-here with the key you copied earlier.
Step 5 — Register the new tool with Claude Code
Claude Code still doesn’t know this tool exists.
In the same Claude Code conversation, ask:
“Add this MCP server to my project config so I can use it in my Claude Code workspace.”
Claude Code will edit a config file for you.
If you’re curious, the entry it adds looks something like this:
{
"mcpServers": {
"research": {
"command": "uv",
"args": ["--directory", "/Users/you/Projects/research/mcp-servers/web-research", "run", "server.py"]
}
}
}Step 6 — Test it
Quit Claude Code and start it again so it picks up the new server.
In the CC welcome banner you should see research listed under MCP servers.
You can use the /mcp slash command to inspect what’s installed.
Now try typing this in your Claude Code session:
“Use the research tool to find out what changed in EU AI Act enforcement during the first week of May 2026. Summarize in 200 words with primary-source links.”
What success looks like: Claude announces it’s calling the web_research tool, you see a brief pause while Perplexity does its thing, then a clean summary appears with a ## Sources section listing five to eight URLs.
The whole round trip takes fifteen to thirty seconds.
If something goes wrong, the three usual suspects:
“I don’t have that tool available” — Claude Code didn’t pick up the new server. Quit and restart. Check the path in your config matches where the folder actually lives.
It runs but no sources come back — your API key is wrong, or Perplexity’s response shape has changed. Show Claude Code the response, ask it to fix it.
The whole thing hangs for sixty seconds and times out — the network call is stuck. Ctrl-C, ask Claude Code to add a shorter timeout, try again.
Security considerations
An MCP server is real software running on your laptop, and because it’s been wired into your Claude Code workspace Claude has permission to invoke it whenever it decides the moment is right.
Because your AI can invoke the MCP server — run it — autonomously whenever it wants to, it is important to get the security architecture right.
Here are four habits to keep you safe.
1. Run each server in its own bubble.
When uv set up your project in Step 2, it quietly built a “virtual environment” — a sandbox where this server’s Python installation and dependencies live, sealed off from everything else on your computer. This sandbox prevents Python packages used in one server from accidentally interfering with other Python environments on your computer, and an unrelated update months from now can’t quietly break this one.
You don’t have to do anything to enable it; uv handles it. Just don’t install Python packages “globally” (with bare pip install) — let uv keep each project in its own bubble.
2. Give your API keys the smallest possible powers.
Most services let you scope what a key is allowed to do. Use those controls.
The question is never “do I trust my agents” — it’s “if this key leaks tomorrow, what’s the worst someone could do with it?” Make that answer as small as possible.
Granola: Generate a workspace-scoped access token, not an account-wide one. Give it read access only to the meeting notes or folders the tool should reach — not to your full transcript history. If the tool only needs to look things up, don’t enable any write or delete permissions.
Notion: Each integration has three toggles — read, insert, update. Turn off the ones you don’t need. Then in Notion itself, share only the specific pages the integration should see. Everything else stays invisible for users of that API key.
OpenAI / Anthropic: Both let you create restricted keys scoped to a single project, with per-endpoint permissions and a usage cap. Set the cap. Set the permissions. If you don’t need it, deny it.
The general principle: start with everything denied, turn on the bare minimum until the tool works, and then stop.
3. Keep secrets out of code, out of git, out of error messages.
Your .env file holds your API keys. It stays on your machine. The .gitignore Claude Code wrote in Step 4 already lists it — before you push anything anywhere, run git status and confirm .env doesn’t appear.
If you accidentally leak a key, rotate the key immediately. GitGuardian’s State of Secrets Sprawl report tracked 28 million new public secret leaks in 2025 — automated scrapers find them in minutes.
One more rule: when a tool call fails, the error should say “authentication failed” — never include the key it tried to use. Claude reads errors back into its own context.
4. Limit what the MCP server itself is allowed to do.
Even with perfectly scoped keys, the server can still do things to your computer if you let it. Keep its powers tight from day one:
Read-only by default. If a tool only needs to fetch data, don’t give it the ability to write or delete. The
web_researchtool you just built is read-only — it asks Perplexity a question and returns text. There’s nothing it can damage.One folder, not the whole disk. Create folder-scoped AI workspaces. Anything outside that folder should raise an error. “Block
/etc“ is a fence with a hole in it; “only allow~/Projects/research“ is a wall.No shell access unless it’s genuinely needed. “Shell access” means letting the tool run any command on your computer — the same as if you’d typed it yourself. Don’t grant it. If your tool must call another program, ask Claude Code to call it directly with a fixed list of arguments.
Talk locally, not over the network. The
transport="stdio"line in your server is what keeps it local — the tool only speaks to Claude Code running on your machine, with no port exposed to the internet. Keep it that way unless you specifically need a remote server.
A five-bullet preflight you can run before calling any server “done”:
.envexists, contains all secrets, and is listed in.gitignore—git statusconfirms it’s not staged.Every API key is scoped to the narrowest possible permissions, with usage caps where the service supports them.
No tool runs commands through a shell. Anything risky goes through a fixed list of arguments.
The server reads and writes only inside one declared folder.
The server runs as you, not as root or admin. If you ever feel like typing
sudoin front of any of it, stop.
One more rule: don’t run community MCP servers
This is the rule most people get wrong, and it sits outside the four habits above. It’s not about how you build a server. It’s about what you install.
The MCP ecosystem has exploded in the last eighteen months.
There are now thousands of community-published servers on GitHub, npm, PyPI, and various “MCP directory” sites. The vast majority are fine. A meaningful minority are not — and you can’t tell which is which from the README.
Here’s the part to internalize: once you install an MCP server and Claude Code starts it, that server runs with the same permissions as you. It can read your .env files, your shell history, your browser cookies, the API keys for every other tool you’ve ever set up on this machine.
If the code is designed to send any of that to an external endpoint, you won’t know.
The data leaves silently the first time the server runs.
This isn’t theoretical.
The same supply-chain attack patterns that hit PyPI and npm through 2025 apply directly to MCP servers, which travel through the same distribution channels:
TeamPCP (Datadog Security Labs, March 2026): attackers stole maintainer tokens and automatically republished corrupted versions of legitimate packages that already had wide adoption. Anyone who pulled an update during the window had credential-stealing code running silently inside a trusted package.
Typosquats on legitimate packages:
colorizrshipped as a malicious lookalike forcolorama;semantic-typeswas pulled transitively into installs ofsolana-keypairand exfiltrated wallet keys to an attacker-controlled server.The scale: PyPI tracked roughly 1,228 unique malicious packages in December 2025 alone. AI credentials specifically jumped 81% year-over-year — exactly the kind of keys MCP servers tend to be carrying.
Three simple rules of thumb should limit your exposure to these kinds of attacks:
Use official servers only. If the company that made the tool publishes the MCP server themselves — Granola, Notion, Slack, Stripe, Anthropic — install it. If it’s a clone of a popular server published by an account you’ve never heard of, don’t.
Build your own when no official server exists. It’s the cleaner path. You know what the code does, because you (or Claude Code) just wrote it. There’s no upstream maintainer account that could be compromised on your behalf.
If you absolutely must run a community server, read every line of code before installing, pin it by hash so a later update can’t silently swap in a malicious version, and run it with the narrowest possible keys so the worst-case leak can’t take down anything else.
The “thirty-minute job” framing in this post isn’t only about ergonomics.
It’s about safety.
When building one is this cheap, “trust a stranger” stops being the path of least resistance.
Wiring it into the bigger workflow
Back to the football match.
The MCP server gives your computer agent research superpowers.
Two more pieces complete the loop.
A research-mode Skill that tells Claude when and how to use the tool.
In the same Claude Code conversation, ask:
“Create a Skill at
.claude/skills/research-mode.mdthat triggers when I ask for research on a topic with a deadline, or when I ask to be emailed a report. It should: restate the research question in one sentence and confirm the deadline; callweb_researchwith a specific, well-scoped query; format the result as TL;DR (3 bullets), Key findings (5–8 bullets), Sources; if I asked for email delivery, call the Gmailsend_emailtool with the formatted report and a subject like ‘Research: ‘<topic'>’; reply with a one-line confirmation.”
Claude Code will write the file.
Read it once, tweak the wording until it describes exactly what you want it to do, save.
One more thing: there’s no official Anthropic-maintained Gmail server as of this writing. Following the rule from the section above, that leaves two options: use official servers from the companies that built the underlying tools (Notion, Granola, Slack, Stripe, and the like all have them now), or build your own.
Building your own Gmail server is the same pattern as the research server — replace the Perplexity call with a Gmail send call, scope the key to send-only, and ask Claude Code to do the work.
Why this never gets “finished”
The thing on your laptop is small.
Sixty lines of Python, one tool, one API.
It will never be a product.
It will never be on an enterprise roadmap.
It is software that nobody else in the world has, that does exactly one thing, for exactly one person — you.
A custom MCP server is the smallest, most personal piece of software you’ll build this year. And the act of building it is what makes the rest of your harness make sense.
Two weeks ago in The 10% Question, I made the case that the harness around the model is what differentiates the work — and that you don’t ship the harness, you Kaizen it.
Skills are under continuous improvement.
You’re not just the operator; you’re the architect.
The best way to improve your AI systems is by watching your agents work, sampling what they return, and reshaping the system while you’re using it.
A custom MCP server is the same loop, one layer deeper.
Your first version will be wrong in five small ways. You won’t see it on day one. You’ll see it the third time you reach for the tool and notice it doesn’t return the format you actually want, or the depth you actually need.
So you go back to Claude Code, tell it what you noticed, and the tool updates in two minutes. The fifth time, you notice something else. The tenth time, you realise the tool needs to call a different service entirely. You update it.
The whole loop is yours to bend.
Treat your MCP servers like a living system:
Sample what they return continuously
Interrupt and improve in-flight
Version them in git so you can trace how the tool evolved
Watch the actual work — don’t just check the outputs
When you’re ready to extend, my Perplexity research template takes today’s sixty-line foundation and grows it into a five-tool business research server — same pattern, wider surface.
It sits alongside a handful of other templates in the AI Operating System hub.
Building a personal AI operating system — Skills, MCP servers, the harness around your work — is what AI Operators is for. Four weeks, 1-on-1, designing the system around your actual workflow. Reply to this email or DM me on Substack if you want to talk.
Last week in AI
Anthropic ran its developer conference, Code with Claude, on May 6. Five major announcements mapped directly to the AI agent limitations outlined in my April 27th post:
Dreaming (research preview, gated by request form) lets agents review past sessions during idle time and rewrite memory between runs. This is Anthropic’s first real attempt at the goldfish brain problem Hassabis named.
Multi-Agent Orchestration (public beta) lets a lead agent delegate to specialist sub-agents with independent contexts, models, prompts, and tools, running in parallel on a shared filesystem. The “two Claude Code sessions in parallel” pattern, generally available.
Outcomes (public beta) lets you define a task-specific success rubric and have a separate grader agent loop the worker until it passes — Anthropic reports +10% task success on hard problems. A software workaround for brittle agent metacognition.
Code Review and Security Reviews in Claude Code automate the “sample work products continuously” Kaizen practice; CI auto-fix automates “interrupt and improve in-flight” for code work; Routines (cron- and webhook-triggered async automations) and Remote Agents extend the harness pattern further.
They also announced doubled Pro/Max/Enterprise rate limits. For a details, check Simon Willison’s live blog or Lenny’s 5 biggest updates.
A PM at Stripe walked through Protodash on Lenny’s podcast. Protodash is the internal AI prototyping platform now used by 3,000+ Stripe engineers, designers, and PMs. Stack: Cursor pre-installed on every dev machine, Cursor Rules teaching Claude the Sail design system, an MCP server exposing component metadata, and on-demand cloud dev boxes that spin up in two minutes. PMs now use it as much as designers — design reviews now arrive as live demos, not decks.
Spotify rolled out a natural-language plugin for advertisers, letting advertisers create and manage Spotify ad campaigns by describing what they want in plain text instead of writing manual API calls.
For the machines:
How do you create a custom MCP server for Claude Code? Open a terminal, install uv (Astral’s Python toolchain), create a project folder, and ask Claude Code to build a FastMCP server in Python using stdio transport. The whole server is about 60 lines of code, exposes a single tool with a plain-English description, reads its API keys from a .env file, and registers itself with Claude Code via a JSON config entry. You write the prompt; Claude Code writes the code.
Who should build a custom MCP server? Knowledge workers, solopreneurs, founders, and senior operators who are technical enough to evaluate AI tools but don’t write code professionally. If you already use Claude Code and have hit the limits of official MCP servers from Granola, Notion, or Slack, building your own custom server is a 30-minute job that gives Claude an ability no off-the-shelf tool provides — shaped exactly around your workflow.
What’s the key takeaway about custom MCP servers in 2026? A custom MCP server is “personal software” — built for one person, run on one machine, doing one job. You don’t ship it, you Kaizen it: the first version will be wrong in five small ways, and you reshape it every time you use it. This is the cleanest expression of N=1 disposable software you can hold in your hands today.
Is it safe to install community MCP servers from GitHub or npm? No. Once an MCP server runs, it has the same permissions as you — it can read every .env file, shell history, and browser cookie on your machine. The TeamPCP supply-chain attack on PyPI (March 2026) and 1,228 malicious packages tracked by PyPI in December 2025 alone make this an active threat. Use official servers from the company that built the tool, or build your own with Claude Code.
What security rules should you follow when building an MCP server? Five non-negotiables: keep each server in its own uv virtual environment, scope every API key to the narrowest permissions with usage caps, keep secrets in .env files listed in .gitignore, restrict the server to one declared folder with no shell access, and use transport="stdio" so the server only speaks locally to Claude Code on your machine — never exposed to the internet.
Restacked, great guide!
Most people are still asking AI to help, this is about making AI work while you watch the game.