MCP, the three primitives, and the SDK rename that breaks lesson four

Introduction to Model Context Protocol is Anthropic's free course on building MCP servers and clients in Python. Fourteen lessons, roughly an hour of video, ending in a graded assessment.

Stated prerequisites: working knowledge of Python, and a basic understanding of JSON and HTTP request-response patterns. The lessons also assume you are comfortable with async and await, which is worth knowing before you start. Environment setup uses uv.

The whole course is built around one running example: a document management server holding a handful of documents in a Python dictionary. Small enough to keep in your head, big enough to demonstrate all three primitives.

Start with the example the course uses. You are building a chat interface where people ask Claude about their GitHub data: which pull requests are open across all their repositories, say.

Claude needs tools to reach GitHub's API. But GitHub is enormous: repositories, pull requests, issues, projects, actions, releases. Without MCP you hand-write a tool schema and a function for every one of them, then test them, then maintain them as GitHub's API changes.

MCP shifts that burden off your server and onto a specialised MCP server. You connect to a GitHub MCP server that already has the tools and schemas defined, and it talks to GitHub's API on your behalf.

Anyone can write an MCP server, and service providers increasingly publish official ones for their own products.

Three roles, and the course is slightly loose about the first one.

The detail worth holding on to: the host creates one client per server. Connect to three servers and the host instantiates three clients, each with its own dedicated connection. A client does not fan out across several servers.

"Local" and "remote" describe where the server runs, not what it is. A local server is typically launched as a subprocess over stdio. A remote one is reached over HTTP and usually serves many clients at once.

This is the sequence worth being able to draw from memory, because it is the most likely thing an interviewer asks you to walk through.

Read it as three conversations rather than eight arrows. Your app talks to the client. The client talks to the server. Your app talks to Claude. Nothing else talks to anything.

Claude enters twice, and this catches people out. Once before the tool call, to be given the question plus the tool list and decide what to call. Once after, to be given the tool result and compose the answer.

On the wire those exchanges are JSON-RPC 2.0 methods: tools/list to discover, tools/call to execute. The Python SDK wraps them in types named ListToolsRequest, ListToolsResult, CallToolRequest and CallToolResult, which is what the course calls them. Same thing, two vocabularies, and it is worth knowing both.

Client and server exchange the same JSON-RPC messages regardless of how those messages travel. That is the point of separating a transport layer from a data layer.

The specification defines exactly two transports.

• stdio. The client launches the server as a subprocess and they talk over standard input and output. Local, fast, no network. Clients should support it wherever possible. One rule that bites people: the server must write nothing to stdout that is not a valid MCP message, so debug prints go to stderr.
• Streamable HTTP. A single endpoint that accepts both POST and GET, with Server-Sent Events used optionally to stream multiple messages back. This is what remote servers use.

Also worth knowing, because it dates any MCP material you read: Streamable HTTP replaced an older HTTP+SSE transport that used two separate endpoints. If a tutorial has you standing up an /sse endpoint next to a POST endpoint, it predates the change. There is more on what that shift means for testers on MCP went stateless.

The course installs the Python SDK and opens with this line:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("DocumentMCP", log_level="ERROR")

On a fresh install today that first line does not run.

ModuleNotFoundError: No module named 'mcp.server.fastmcp'.
This is mcp 2.x, where FastMCP was renamed to MCPServer
(from mcp.server.mcpserver import MCPServer) and other APIs changed

The SDK went to 2.x and renamed the class the entire course is built on. A plain pip install "mcp[cli]" now gives you 2.1.1, and every code sample in the course fails at import.

Two ways forward, both checked:

On 2.x the same server becomes:

from mcp.server.mcpserver import MCPServer

mcp = MCPServer("DocumentMCP", log_level="ERROR")

The decorators are unchanged. @mcp.tool, @mcp.resource and @mcp.prompt register exactly as the course shows, and tools and resources come back correctly. What did change is the shape of the objects you read back: the SDK moved from camelCase to snake_case, so tool.inputSchema is now tool.input_schema. Anything in your own code that inspects the returned types needs the same treatment.

The pitch for the SDK is that you never write a JSON schema. Type hints and Pydantic Field descriptions become the schema Claude sees.

@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")

    return docs[doc_id]

Three things combine into the schema: the decorator supplies name and description, the type hints supply types and drive validation, and the Field descriptions explain each argument.

The edit tool is where the field descriptions start doing real work:

@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")

    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Read the old_str description again. "Must match exactly, including whitespace" is not documentation for you, it is an instruction to Claude, and it is the difference between a tool that works and one that silently replaces nothing. Descriptions are load-bearing.

Error handling comes free: raising an ordinary Python ValueError is enough, and the SDK turns it into a proper error response.

A browser-based inspector ships with the SDK, so you can exercise a server without building a client first. This part of the course still holds exactly: the command is unchanged in both 1.x and 2.x.

mcp dev mcp_server.py

It prints a local URL, typically around http://127.0.0.1:6274. Open it, press Connect, and watch the status move from Disconnected to Connected. Then the tabs for Resources, Tools and Prompts each have a List button, and selecting an entry gives you input fields and a Run button.

The property that makes it genuinely useful: the inspector holds server state across calls. Run the edit tool, then immediately read the same document, and you can confirm the change persisted. That makes multi-step workflows and error paths testable without writing a test script.

If a tool is a POST handler, a resource is a GET handler. Reach for a resource when you want to fetch information rather than perform an action.

The motivating feature is a document mention: typing @plan.md in a chat box. That needs two operations, and they are different shapes.

@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

The direct resource has a static URI and takes no parameters. The templated one carries {doc_id} in the URI, and the SDK parses it out and hands it to your function as a keyword argument. The inspector reflects the split too, listing them under separate Resources and Resource Templates sections.

mime_type tells the client how to interpret what comes back, and the SDK serialises the return value for you. Return the list, not json.dumps(the_list).

On the client side, one method covers both, branching on that MIME type:

async def read_resource(self, uri: str) -> Any:
    result = await self.session().read_resource(AnyUrl(uri))
    resource = result.contents[0]

    if isinstance(resource, types.TextResourceContents):
        if resource.mimeType == "application/json":
            return json.loads(resource.text)

    return resource.text

It reads contents[0] because a read usually concerns one resource, even though the result arrives as a list.

The honest question about prompts: a user can already ask Claude to reformat a document, and it will do a decent job. So why ship a prompt?

Because you can invest in it and they cannot. As the server author you write it once, test it against edge cases, evaluate it, and improve it. Every user gets that work without needing to be a prompt engineer.

@mcp.prompt(
    name="format",
    description="Rewrites the contents of the document in Markdown format."
)
def format_document(
    doc_id: str = Field(description="Id of the document to format")
) -> list[base.Message]:
    prompt = f"""
    Your goal is to reformat a document to be written with markdown syntax.

    The id of the document you need to reformat is:
    <document_id>
    {doc_id}
    </document_id>

    Add in headers, bullet points, tables, etc as necessary.
    Use the 'edit_document' tool to edit the document.
    """

    return [
        base.UserMessage(prompt)
    ]

Two details. It returns a list of messages, so you can stage a multi-turn exchange with both user and assistant messages, not just one block of text. And the prompt tells Claude to use the edit_document tool: prompts and tools compose. A prompt is a scripted way to drive the tools you already exposed.

On the client, arguments arrive as a dictionary and become keyword arguments on the server function:

async def get_prompt(self, prompt_name, args: dict[str, str]):
    result = await self.session().get_prompt(prompt_name, args)
    return result.messages

So {"doc_id": "plan.md"} interpolates into the template. The inspector shows the fully interpolated messages before you ship, which is the point at which you catch a template that reads badly.

This is the conceptual payoff of the course, and the single most likely assessment question.

Tools are model-controlled. Claude decides when to call one and consumes the result. This is how you give Claude an autonomous capability.

Resources are app-controlled. Your application code decides when to fetch and what to do with the data, usually to drive UI or add context. The real-world shape is an "Add from Google Drive" button: your code decides what to show and what to inject.

Prompts are user-controlled. A person triggers one deliberately, through a slash command, a menu, or a button under the chat input.

The compressed version, worth memorising: tools serve the model, resources serve your app, prompts serve your users. These are guidelines rather than hard rules, and the course says so, but they resolve most design questions on their own.

The course teaches three primitives and calls it the picture. It is half the picture. Those three are server features, things a server offers a client. The specification also defines client features, things a client offers a server.

Elicitation is the current one. It lets a server ask the user for more information mid-operation, or ask them to confirm an action, via elicitation/create. For anything with a destructive step, that is the difference between a server that guesses and one that asks.

Two more exist and are now deprecated, which matters mostly so you recognise them in older material:

• Sampling let a server request a completion from the client's model, so a server could use an LLM without bundling an SDK. New implementations are told to integrate with a provider API directly.
• Logging let a server send log messages to the client. New implementations should log to stderr on stdio, or use OpenTelemetry.

Beyond the primitives there is a good deal the course does not touch: a mandatory server/discover request for capability and version negotiation, opt-in change notifications through subscriptions/listen, caching hints on results, pagination on list methods, and a Tasks extension for long-running work. None of it is needed to finish the course. All of it is on the spec.

The concepts hold up well. The specifics have drifted. Take the assessment on the course's answers; build on these.

These cover the assessed material rather than reproducing the course's own assessment. Answers are hidden.