Claude with MCP

1 · What MCP is essential

Picture the drawer of chargers you've accumulated over the years. Every phone, camera and laptop shipped its own plug, so you kept a tangle of incompatible cables just in case. Then USB-C arrived and one connector fit almost everything. AI tooling had exactly that drawer-of-chargers problem: every app that wanted Claude to search a database, read a file, or file a ticket had to write its own bespoke integration, and none of that work carried over to the next app. MCP is the USB-C moment — one connector, written once, that any tool-using client can plug into.

Here's the idea in one sentence, and it's worth reading slowly: the Model Context Protocol is an open standard for connecting an LLM to outside tools and data. "Open standard" is the load-bearing phrase — MCP isn't an Anthropic-only product feature, it's a published specification anyone can implement, which is precisely why the same server you write today works with Claude, with your own code, and with other MCP-aware clients tomorrow. You write a capability once as an MCP server, and any MCP-aware client (Claude Code, the desktop app, your own application) can use it. Instead of N custom integrations — one per app — you build one server that speaks the protocol, and the N clients come to it.

The analogy that unlocks the whole chapter: think of it as a client/server split, the same shape as a web browser talking to a web server. The client lives where Claude runs and knows how to ask; the server is the program you write and knows how to do. They're two separate processes that talk over the standard protocol, and neither needs to know the other's internals — only the shared contract between them.

The common mistake is hearing "MCP" and picturing a new kind of AI model, or some magic that makes Claude smarter. It's neither. MCP adds no intelligence; it's plumbing — a well-specified way to move a request from the model to your code and a result back. The value isn't cleverness, it's reuse and interoperability: build the integration to your ticket system once and every agent, teammate, and app inherits it for the cost of a config line. Keep that framing as you read — everything below is just detail on how the client, the protocol, and the server play their three roles.

2 · The three primitives essential

Once you've decided to speak a standard, the next question is: standard for what? A protocol is only as useful as the vocabulary it agrees on. MCP's answer is refreshingly small — a server can offer just three kinds of thing, and every capability you'll ever build is one of them. Learning these three words is most of learning MCP; the rest is syntax.

Think of the three primitives as answering three different questions Claude might have. Can I do something? — that's a Tool, an action the model can call, like search_docs or create_ticket. Can I read something? — that's a Resource, a piece of data the model can pull in, like a file, a database row, or an API result. Is there a ready-made way to ask? — that's a Prompt, a reusable prompt template the server offers, like "summarize this incident." Verbs, nouns, and phrases: actions, data, and templates.

The distinction that trips people up is Tool versus Resource, and it's worth getting straight now. A Tool does — it runs code, and calling it can change the world (send an email, delete a record). A Resource is — it's content the model reads, ideally with no side effects, like opening a file. The rough rule of thumb: if invoking it could change something, it's a Tool and deserves the caution Tools get; if it only surfaces information, it's a Resource. Muddling the two — say, hiding a destructive action inside something you called a "resource" — is how you end up with a server that behaves surprisingly and dangerously.

Why does this matter beyond tidiness? Because the client treats the three differently: Tools are the ones Claude actively chooses to call mid-task, and they're the ones that get approval prompts and least-privilege scrutiny (section 6). Most of this chapter is about Tools for exactly that reason — they're where the action, and the risk, lives. The table below is your reference card; keep it in view as the labs build a Tool from scratch.

3 · Connect Claude to a server essential

A server nobody knows about is just a script sitting on disk. You've understood what MCP is and the three things a server can offer — but Claude can't use a single one of them until the client is told the server exists. This section is the introduction step: the moment you hand the client an address and say "there's a capability over here, go talk to it."

The helpful surprise is how little you do. You don't wire up each tool by hand, register function names, or describe the protocol — you just tell the client how to start the server, and MCP handles the rest. Think of it like adding a contact to your phone: you save the name and number once, and from then on you just say who you want to reach. Here that "contact card" is a small block in the client's config file naming the server and the command that launches it.

The mechanism underneath is discovery, and it's the part beginners don't expect. When the client starts your server, the two shake hands over the protocol and the client asks the server what it can do; the server answers with its list of tools, their descriptions, and their input shapes. That's why you never enumerate tools in the config — add a new @mcp.tool() function to the server and the client picks it up automatically the next time it connects. The config points at the server; the server advertises its own tools.

The config below launches a stdio server — the simplest local case, where client and server are two processes on the same machine talking over standard-in/standard-out pipes (the same channels a normal program uses for input and output). The common confusion to head off: this file is not run like a program and prints nothing. It's a registration record. Its only job is to make Claude aware of the docs server so that, in a session, Claude can reach for its tools when a request calls for them. Read the walkthrough after it line by line.

mcp.json// .claude/mcp.json (or via `claude mcp add`)
{
  "mcpServers": {
    "docs": {
      "command": "python",
      "args": ["mcp/server.py"]        // a stdio server (your process)
    }
  }
}
// Claude now sees the server's tools and can call them in a session.

4 · Intermediate — build a minimal server intermediate

Here's the moment MCP stops being a diagram and becomes something you own. Up to now the server has been "the box on the right" — the thing that does the work. Now you write it, and the reveal is that it's astonishingly small: a handful of ordinary Python functions with one line of decoration each. If you were bracing for protocol boilerplate — message framing, request IDs, capability negotiation — relax. You write none of it.

The reason is a library called FastMCP, and the way to think about it is a waiter in a restaurant. You (the kitchen) just cook — you write plain functions that do a job. FastMCP is the waiter who takes the order from the client, carries it to your function, plates the result, and delivers it back, speaking the protocol so you never have to. Your entire responsibility is the food: correct functions with clear descriptions. Everything about how the request and response travel is the waiter's problem, not yours.

The one piece of new syntax is the decorator — the @mcp.tool() line sitting on top of a function. A decorator is Python's way of tagging a function with extra behaviour without changing its body; here the tag means "expose this one to Claude as a callable tool." That word "expose" is the whole point: a function without the decorator is invisible to Claude, and a function with it becomes a capability the client can discover and call. Adding a tool is literally adding a decorated function — nothing more.

The mistake that costs people an afternoon is treating the function's docstring as a throwaway comment. It is not. MCP ships that docstring to Claude as the tool's official description — it's the entire basis on which Claude decides whether to call the tool. A blank or vague docstring produces a tool Claude technically has but never reaches for, which feels exactly like a bug and isn't one. We give the tool contract its own section (5) precisely because this is where beginners lose the most time. For now, read the server below and notice how the docstring names when to use the tool, not just what it does.

server.pyfrom mcp.server.fastmcp import FastMCP

mcp = FastMCP("docs")

@mcp.tool()
def search_docs(query: str) -> list[str]:
    """Search the internal knowledge base. Use for policy/product questions."""
    corpus = {"refund": "Refunds within 30 days.", "hours": "Support 9-5 ET."}
    return [v for k, v in corpus.items() if query.lower() in k]

if __name__ == "__main__":
    mcp.run(transport="stdio")

5 · The tool contract — a description that gets called intermediate

You can write a flawless tool and watch Claude ignore it completely. The code runs, the server connects, everything looks right — and yet when you ask the question the tool was built for, Claude answers from memory or says it can't help. Nine times out of ten the tool isn't broken; its description is. This is the single most common frustration people hit with MCP, and it deserves its own section because the fix is a mindset, not a line of code.

Here's the reframe: Claude never sees your function's body. At decision time it sees a menu — a list of tool names and their descriptions — and it picks the one whose description best matches what the user just asked. So the description isn't documentation about the tool; it is the tool, as far as Claude's choice is concerned. Think of it like a job posting. "Search" is a title with no job description — nobody knows when to apply. "Search the internal knowledge base; use for policy, product, and refund questions" tells Claude exactly the situations to reach for it. Same tool, wildly different hit rate.

The instinct to fight is describing what the tool does instead of when to use it. "Searches documents" is what; "use for policy and product questions" is when. Claude already has to match a user's request to a tool, so it needs the trigger conditions — the situations, the keywords, the kinds of question — far more than a mechanical summary. A good description reads like advice to a new teammate: reach for this one whenever someone asks about X or Y. This is the same principle behind a Skill's description (K4) or a tool schema (Ch 4) — the model routes on the words you give it.

The lab below turns that judgment into something you can test. It's a tiny linter that scores a description the way a reviewer would: does it name a when-to-use, and is it long enough to match reliably? Treating your descriptions as testable artifacts — lint them, iterate until they pass — is what separates tools that fire at the right moment from tools that quietly gather dust.

tool_desc.pydef score_tool_desc(desc):
    d = desc.lower(); notes = []
    if not any(w in d for w in ["use ", "when", "for"]): notes.append("say WHEN to use it")
    if len(desc) < 25: notes.append("too terse to trigger reliably")
    return (not notes), notes

print(score_tool_desc("searches"))
print(score_tool_desc("Search the internal KB. Use for policy/product/procedure questions."))

(False, ['say WHEN to use it', 'too terse to trigger reliably'])
(True, [])

6 · Advanced — MCP is a trust boundary advanced

The friendliness of the config file hides a sharp edge. Adding an MCP server is two lines of JSON, which makes it feel as harmless as adding a bookmark. It is not. When you connect a server, you're granting a program the right to run on your machine, with your permissions, and to act on Claude's behalf. That's closer to installing an app than saving a link — and the casual ergonomics are exactly what make the risk easy to miss.

The mental model to hold is a trust boundary: a line where things you control meet things you don't, and where you should slow down and check credentials. A convenient way to picture it is handing someone the keys to your house. A trusted friend who's just fetching the mail is one thing; a stranger, holding a key that also opens the safe, whom nobody has vetted, is another entirely. The server is the person; the tools it exposes are which rooms the key opens. You want to know who wrote it, what it can reach, and whether anyone's watching when it does something irreversible.

Three properties turn a server from "probably fine" into "genuinely dangerous," and they stack. First, an untrusted source — you don't know who wrote the code you're about to run. Second, network access without an audit — code that can reach the internet and hasn't been reviewed can quietly exfiltrate whatever it touches. Third, a destructive tool with no human gate — an action that deletes or overwrites, running with no approval prompt in the loop. Any one warrants caution; together they're a server you simply don't connect.

The professional habits that defuse all of this are least privilege (give a tool only the access it truly needs, never blanket permissions) and keeping the client's approval prompts on for anything state-changing, so a human sees and okays irreversible actions. The common mistake is treating vetting as a one-time gut feeling; the fix, shown in the lab, is to encode the judgment as a repeatable checklist you run before enabling any server. Model the risk first, connect second.

vet_server.pydef vet_server(server):
    risks = []
    if not server.get("trusted_source"): risks.append("untrusted source")
    if server.get("network_access") and not server.get("audited"): risks.append("network access, unaudited")
    if "delete" in server.get("tools", []) and not server.get("human_gate"): risks.append("destructive tool, no gate")
    return (not risks), risks

print(vet_server({"trusted_source": True, "tools": ["search"], "audited": True}))
print(vet_server({"trusted_source": False, "network_access": True, "tools": ["delete"]}))

(True, [])
(False, ['untrusted source', 'network access, unaudited', 'destructive tool, no gate'])

7 · Professional — where MCP fits your stack professional

The trap of learning a shiny new tool is wanting to use it everywhere. You've now built a server, connected it, and vetted it — and the natural next thought is "great, I'll make everything an MCP server." Resist it. The professional skill isn't building servers; it's knowing when a server earns its keep and when a plain function is the better answer. Reaching for the protocol on a one-off tool is over-engineering with extra steps.

The deciding question is how many clients will use this capability. MCP's entire payoff is reuse across a boundary: write the ticket-system server once, and Claude Code, your own app, and every subagent (K5) plug into the same thing with a config line. That's the "USB-C" leverage — one server instead of one integration per app. But leverage only pays off when there's something to reuse. If exactly one program will ever call the capability, the protocol, the separate process, and the config all buy you nothing.

An analogy: you don't stand up a shared microservice to add two numbers for a single script — you write a function. You do stand one up when three teams need the same billing logic and you're tired of it drifting out of sync in three codebases. Same calculus here. A helper used by one client, once, is a function; a capability that multiple clients or agents will lean on is a server. The rough rule of thumb: two or more consumers → server; a single caller → function.

The mistake to name plainly is cargo-culting — copying the server pattern because it's the "proper" way, not because your situation needs it. A server adds a process to launch, a protocol to speak, and config to maintain; that overhead is a bargain when the capability is shared and pure waste when it isn't. Match the tool to the reuse, and you'll build servers exactly where they multiply your effort and functions everywhere else.

8 · Tech-lead — MCP servers as shared infrastructure tech-lead

The moment a server is shared, it stops being your script and becomes everyone's dependency. A tool three teams rely on can't be quietly edited on a Friday afternoon, can't silently change what it returns, and can't disappear because you refactored. That shift in stakes is what separates a personal server from infrastructure — and stewarding that shift is the tech-lead's job in this chapter.

The most useful reframe is to stop thinking of an internal MCP server as "an AI thing" and start treating it exactly like a shared internal API — because operationally that's what it is. Nobody would ship a company-wide API with no version numbers, no docs, no access control, and no monitoring; the same discipline applies the instant a server has more than one consumer. The four load-bearing properties are the same ones you'd demand of any service others depend on: versioned (semver, so clients can pin and you can evolve without breaking them), documented (every tool's description names when to use it — the section-5 lesson, now a contract others read), access-controlled (least privilege, with auth on state-changing tools), and monitored (log tool calls, alert on failures and abuse).

Notice this is the section-6 trust-boundary lesson turned inward. When you connect a third-party server, you vet it; when you ship one to your org, you're the party being trusted, so the non-negotiables become your responsibility: least privilege by default and approval prompts left on for anything destructive. A shared server that skips these doesn't just risk your machine — it hands every teammate who connects the same sharp edge, multiplied.

The payoff makes the discipline worth it. One well-built, trusted server becomes the tool layer the whole organization builds on — every agent and engineer gains that capability for the cost of a config line, the same leverage as a shared client library that everyone imports instead of everyone re-implementing. That is the endgame of MCP: not a scattering of one-off scripts, but a small, governed set of servers that turn "connect to our systems" from a project into a one-liner. (The deep version — registries, remote transports, org rollout — is K6.)

// .claude/mcp.json (or via `claude mcp add`)
{
  "mcpServers": {
    "docs": {
      "command": "python",
      "args": ["mcp/server.py"]        // a stdio server (your process)
    }
  }
}
// Claude now sees the server's tools and can call them in a session.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("docs")

@mcp.tool()
def search_docs(query: str) -> list[str]:
    """Search the internal knowledge base. Use for policy/product questions."""
    corpus = {"refund": "Refunds within 30 days.", "hours": "Support 9-5 ET."}
    return [v for k, v in corpus.items() if query.lower() in k]

if __name__ == "__main__":
    mcp.run(transport="stdio")

def score_tool_desc(desc):
    d = desc.lower(); notes = []
    if not any(w in d for w in ["use ", "when", "for"]): notes.append("say WHEN to use it")
    if len(desc) < 25: notes.append("too terse to trigger reliably")
    return (not notes), notes

print(score_tool_desc("searches"))
print(score_tool_desc("Search the internal KB. Use for policy/product/procedure questions."))

(False, ['say WHEN to use it', 'too terse to trigger reliably'])
(True, [])

def vet_server(server):
    risks = []
    if not server.get("trusted_source"): risks.append("untrusted source")
    if server.get("network_access") and not server.get("audited"): risks.append("network access, unaudited")
    if "delete" in server.get("tools", []) and not server.get("human_gate"): risks.append("destructive tool, no gate")
    return (not risks), risks

print(vet_server({"trusted_source": True, "tools": ["search"], "audited": True}))
print(vet_server({"trusted_source": False, "network_access": True, "tools": ["delete"]}))

(True, [])
(False, ['untrusted source', 'network access, unaudited', 'destructive tool, no gate'])

# Rule: reach for an MCP server only when a capability is used by
# MULTIPLE clients/agents. For one client, one-off, a plain
# function is simpler — don't cargo-cult a server.

def decide(capability):
    if capability["num_clients"] >= 2 or capability["shared_across_agents"]:
        return "MCP server: build once, every client plugs in"
    return "plain function: one client, one-off — keep it simple"

print(decide({"num_clients": 1, "shared_across_agents": False}))
print(decide({"num_clients": 3, "shared_across_agents": True}))

plain function: one client, one-off — keep it simple
MCP server: build once, every client plugs in

# A lead treats an internal MCP server like a shared API.
SHARED_SERVER_STANDARDS = {
    "versioned":        "semver the server; clients pin a version",
    "documented":       "each tool's docstring says WHEN to use it",
    "access_controlled": "least-privilege; auth on state-changing tools",
    "monitored":        "log tool calls; alert on failures/abuse",
    "human_gated":      "approval prompts stay ON for destructive tools",
}

def ready_to_share(server):
    missing = [k for k in SHARED_SERVER_STANDARDS if not server.get(k)]
    return (not missing), missing

print(ready_to_share({k: True for k in SHARED_SERVER_STANDARDS}))
print(ready_to_share({"versioned": True, "documented": True}))

(True, [])
(False, ['access_controlled', 'monitored', 'human_gated'])

Knowledge check check yourself