Skip to content

Part 5, MCP fundamentals ​

Knowledge-share outline ​

  1. Why everyone forks the same application before designing (everyone starts level).
  2. What MCP is and why it matters: a common interface for context, prompts, and tools.
  3. The client/server mental model: agent as client, capability provider as server.
  4. Resources, read-oriented context: package data, route data, schema, policy documents.
  5. Prompts, reusable, named workflows such as "investigate a delayed package."
  6. Tools, callable actions such as look up order, parse label, update package status.
  7. How MCP differs from a normal REST API in an agentic workflow.
  8. What you will design, and how it feeds the Part 6 build.

At a glance ​

Start stateEnd stateFallback baseline
Your Part 4 spec and your fork of package-thisAn MCP design mapping the application's capabilities to resources, prompts, and toolsMCP design reference

Learning goals ​

  • Explain MCP (Model Context Protocol), an open standard for exposing context, prompts, and tools to AI applications, and the problems it solves.
  • Describe the MCP client/server model: the agent is the client, the capability provider is the server.
  • Distinguish MCP resources, prompts, and tools, and map package-this capabilities onto them.

Getting everyone on the same page ​

Before the MCP design work, everyone forks the same application so the design exercise has a single, consistent starting point regardless of what you built in Parts 1-4.

Fork the application on GitHub:

  1. Go to dundermifflin.nl/package-this.
  2. Click Fork and fork it to your own GitHub account.
  3. Clone your fork locally:
bash
git clone https://github.com/<your-username>/package-this
cd package-this

Expected output: the package-this directory is on your machine. It is a Python package manager with a REST API, role-based access, domain events, and an audit trail: the same kind of application you specified in Part 4.

This fork is the application your agents will operate against for the rest of the workshop.

Why it matters ​

In the parts so far, you have built an agent with memory and produced a spec for your own application. But the application those agents will call (package-this) has capabilities that are still unstructured from the agent's point of view. Before we make the agent act, we need a structured way to describe what context it can read and what actions it can take.

That structure is MCP. Designing it now, before any server exists, means the afternoon build in Part 6 is wiring up a clear plan rather than inventing one under time pressure.

What you will build ​

Not code, a design. By the end you will have an MCP design for package-this: a mapping of at least five capabilities to MCP resources, prompts, or tools, draft input/output contracts for at least three tools, a read-only vs approval-required marker on each operation, and a short checklist to carry into the Part 6 server build.

MCP concepts ​

MCP defines three primitives. The skill is choosing the right one for each capability, not turning everything into a tool.

  • Resources, read-oriented context the agent can pull in. In package-this: the package dataset, route data, the data schema, and policy documents. Resources are things the agent reads, not actions it performs.
  • Prompts, reusable, named workflows the server offers. For example, "investigate a delayed package" bundles the steps and context for a recurring task so it is not re-typed as free text each time.
  • Tools, callable actions with typed inputs and outputs. For example, look up order, parse label, and update package status. Tools are where the agent does something.

Client/server model: the agent is the MCP client; the component that exposes the resources, prompts, and tools is the MCP server. The client discovers what the server offers and calls it over a consistent interface, so the same package capabilities can back many agents later (the reuse we build on in Part 6).

There is more to explore

Resources, prompts, and tools are the foundation, but MCP is a growing standard. Two concepts worth knowing about as you go deeper:

  • Elicitation: a mechanism that lets the server ask the client (and therefore the user) for additional input mid-conversation, useful when a tool needs clarification before it can act.
  • Sampling: lets the server request a model completion from the client, enabling server-side reasoning without the server holding its own model connection.

The full specification and all current primitives live at modelcontextprotocol.io.

How MCP differs from a normal REST API ​

A REST (representational state transfer) API, an application programming interface, is a set of hand-wired endpoints a developer reads documentation for and calls. MCP primitives are discoverable and typed for the model: each resource, prompt, and tool carries a description the agent can read at runtime to decide what to use, rather than the integration being hard-coded endpoint by endpoint. We treat this conceptually here, we are not walking through every protocol message.

Descriptions are runtime instructions, not docs

The agent reads descriptions to decide what to call. A vague description means the wrong tool gets called. Write each one for the agent: what it does, what it expects, and when to use it.

Lab steps ​

You are designing, not coding. Capture your answers in the design table below (copy it into your notes or the baseline's design file).

  1. Explore the application. Open your package-this fork and find the existing capabilities: package lookup, order status, route data, label parsing, status updates. List them before you start mapping.

    Expected output: a list of five or more capabilities you can see in the codebase or its README.

  2. Map at least five capabilities to an MCP resource, prompt, or tool, and write a one-line description for each.

    Expected output: five or more rows in the design table, e.g. package data β†’ resource, "investigate a delayed package" β†’ prompt, look up order β†’ tool. Read-oriented context lands on resources; reusable workflows land on prompts, not everything is a tool.

  3. Draft contracts for at least three tools. For each tool, name its inputs and its expected output.

    Expected output: for example, parse label, input label: string β†’ output { order, fragile, route }; look up order, input orderId: string β†’ output { status, route, condition }.

  4. Mark each operation read-only or approval-required. Read-oriented and lookup operations are read-only; anything that changes state is approval-required (we mark it now; approval itself, HITL, human-in-the-loop, is built in a later segment, not here).

    Expected output: e.g. look up order β†’ read-only; update package status β†’ approval-required.

  5. Assemble your MCP design checklist for the afternoon. Check the design table below on what is expected.

    Expected output: a short checklist confirming your resources, prompts, and tools are listed, three tools have input/output contracts, and each operation has a read-only or approval marker.

Design table ​

Fill one row per mapped capability, this is your work, not a worked answer key. The first row shows the format; complete the rest yourself. For resources and prompts, leave the tool-only columns blank. Try to get at least one resource, prompt and tool in there. (Stuck or out of time? The fully worked version is in the fallback baseline.)

CapabilityMCP conceptDescriptionInputsOutputRead-only / approval
Package dataresourceCurrent packages, status, route, conditionread-only
…add β‰₯4 more, incl. β‰₯3 tools…

Aim for at least five rows, but more is better, including at least three tools with named inputs, an expected output, and a read-only or approval-required marker. Use these helper prompts as agentic inspiration to fill it in:

  • Resources (read-oriented context): what data and policy documents must the agent read?
  • Prompt (reusable workflow): what recurring task, like "investigate a delayed package", would you package up?
  • Tools (callable actions): which actions change or fetch state? For example look up order (orderId: string β†’ { status, route, condition }, read-only) and update package status (packageId: string, status: enum β†’ { ok: boolean }, approval-required).

Checkpoint ​

  • Your design maps at least five capabilities to MCP resources, prompts, or tools.
  • At least three tools have named inputs and an expected output.
  • Every operation is marked read-only or approval-required.
  • You have an MCP design checklist ready for Part 6.

See How checkpoints work.

Fallback baseline ​

If you are short on time, a fully worked MCP design for package-this is available at MCP design reference. Review it, adopt the mapping, and move on; you lose nothing for the Part 6 server build.

Troubleshooting ​

  • Everything looks like a tool, if a capability only reads data, it is a resource; if it is a recurring multi-step task, it is a prompt. Reserve tools for actions that do something. More help on Troubleshooting.
  • Stuck on inputs/outputs: borrow the shapes from package-this's existing endpoints; the label and order formats are already defined there.
  • Out of time: review the MCP design reference and move on; you lose nothing for Part 6.

Optional stretch task ​

Add a second prompt (for example, "prepare a route summary for the morning") and a fourth tool, then note which existing resource each one would read from. This previews how a single MCP server can serve many workflows, the reuse we exploit in Part 6.

Source-backed background ​

  • What MCP is: the Model Context Protocol is an open standard for connecting AI applications to external context and capabilities, primary source: modelcontextprotocol.io.
  • The three primitives: see the official MCP documentation for resources, prompts, and tools. The docs describe resources as context to read, prompts as reusable templated workflows, and tools as callable functions, exactly the distinction the lab applies to the package manager.

For the full source list, see References.

Apply it: De LeesLantaarn ​

Apply it to your own solution

Map De LeesLantaarn onto MCP. The unreliable BMS and the flaky external book API are exactly the kind of capabilities you would put behind an MCP server so many agents share one guarded interface. Which reads become resources (a book's age category, genre, stock), which flows become prompts, and which actions become tools (borrow_book, place_backorder)? Note where you would add retries or a cached fallback so the API's instability does not sink the whole agent.

What we will not cover ​

  • Building the MCP server, that is Part 6; this part is design-only.
  • A walkthrough of every protocol message or transport detail, we stay at the concept level.
  • Turning every operation into a tool, read context maps to resources, workflows to prompts.

    WARNING

    Be very careful of just wrapping an entire existing API with an MCP server!

  • Implementing human approval, we only mark approval-required operations; Human-In-The_loop (HITL) is a later segment.

Previous: Part 4, Writing useful specs & personas Β· Next: Part 6, Build the MCP server