Welcome back! In the last lesson, you learned how to define and expose the main building blocks of an MCP server: tools, resources, and prompts. You saw how to make these primitives discoverable and usable by clients, and you practiced connecting to your server and interacting with each type. This lesson will build directly on that foundation.

In this lesson, you will learn how to take a real-world service — in this case, a shopping list manager — and expose its actions as MCP tools. You will see how to wrap service methods as tools, document them clearly, and make them available for clients to discover and use. By the end of this lesson, you will be able to define, document, and implement practical MCP tools for a service, and you will know how to connect to your server and interact with these tools manually. This will prepare you for more advanced integrations, such as connecting your server to an AI agent, which we will cover in the next lesson.

To make this lesson practical, we will use a simple shopping list service as our example. The shopping list service is implemented in a file called shopping_list.py. This service manages a collection of shopping items, each with an ID, name, quantity, and purchased status. The service provides methods to add items, remove items, mark items as purchased or not, and fetch the list of items (optionally filtered by whether they have been purchased).

You do not need to write the shopping list logic yourself — the code is already provided for you. Here is a quick look at the core of the service:

This service is a typical example of a backend component you might want to expose to AI agents or other clients. By wrapping its methods as MCP tools, you make it possible for clients to add, remove, and update shopping list items in a standardized way.

Before you can expose the shopping list service’s actions as MCP tools, you need to set up your MCP server and create an instance of the shopping list service.

With this setup, your MCP server instance is ready to register tools, and your shopping_list service instance is ready to handle shopping list operations.

To expose the shopping list service’s actions as MCP tools, you will use the @mcp.tool() decorator, just as you did in the previous lesson. Each tool is a Python function that calls the appropriate method on the service. It is important to provide clear docstrings for each tool, describing what it does, what parameters it takes, and what it returns. This documentation is not just for humans — it is also used by clients and AI agents to understand how to use your tools.

Let’s start by defining a tool to fetch shopping list items. This is a common operation that clients will need, and it demonstrates how to expose a service method as a tool with clear documentation.

Notice how the docstring explains what the tool does, lists the parameters with their types and descriptions, and describes the return value. This level of documentation is essential for making your tools easy to use and understand, especially when clients or AI agents are discovering them dynamically.

In MCP, both tools and resources can be used to expose information to clients, but they are designed for different scenarios.

Tools are model-controlled, which means AI agents and clients can invoke them directly and autonomously. Tools can accept parameters, perform logic, and return results dynamically. This makes them ideal for retrieving data that may change over time, needs to be filtered, or requires real-time access. For example, fetching shopping list items—especially when you want to filter by purchased status or always get the most current data—is best implemented as a tool. This allows agents to request exactly the data they need, when they need it, as part of a conversation or workflow.

Resources are application-controlled and are typically used to provide static or pre-defined data, such as documentation or reference material. The client application decides when and how to use resources, and agents cannot invoke them directly in the same way as tools. This makes resources less suitable for dynamic data retrieval or actions that require parameters.

For the shopping list service, exposing data-fetching as a tool ensures that agents can always retrieve the latest information, apply filters, and interact with the service in a flexible, real-time manner. This is why we use a tool—not a resource—to return shopping list data.

Now, let’s walk through the other main tools you will expose for the shopping list service. Each tool wraps a method from the service and provides a clear interface for clients.

The add_item tool allows clients to add a new item to the shopping list. It takes a name and quantity, and returns the unique ID of the new item.

The remove_item tool lets clients remove an item by its ID. It returns True if the item was removed successfully, or False if no item with that ID was found.

The mark_purchased tool allows clients to mark an item as purchased or not purchased. It takes the item’s ID and a boolean flag, and returns True if the update succeeded.

Each of these tools is now discoverable and callable by any MCP client. The clear docstrings make it easy for both humans and AI agents to understand how to use them.

Once your tools are defined, you can run and connect to your server using the MCP client interface. For local development and testing, the stdio transport is commonly used. Here’s a reminder of how to connect to your MCP server:

After connecting to the server, you can discover which tools are available and inspect their documentation and input schemas. This is a crucial step, as it allows you (or any client, including AI agents) to understand what actions the server exposes and how to use them.

To demonstrate this, let’s list all available tools and print out their key details:

Running this code will output something like the following for each tool:

This demonstration shows how you can programmatically explore the server’s capabilities, making it easy to see what actions are available and how to call them.

Let’s walk through how to use these tools in practice. First, we’ll add a new item to the shopping list, and then we’ll fetch the updated list to verify the change.

To add an item, call the add_item tool with the desired name and quantity:

This demonstrates how to invoke a tool and handle its response. The output will look like:

Next, let’s fetch the current shopping list items to confirm that the new item was added:

This will display the full list of items, including the one you just added:

By following these steps, you can see how to discover, call, and verify the behavior of MCP tools in a real-world scenario. This hands-on demonstration shows the full cycle: exploring available actions, invoking them, and checking the results.

In this lesson, you learned how to take a real-world service and expose its actions as MCP tools. You saw how to wrap service methods with the @mcp.tool() decorator, document them clearly, and handle inputs and outputs in a way that is easy for clients and AI agents to use. You also practiced running the MCP server and connecting to it manually from a client, listing available tools, and calling them with real data.

These skills are essential for building practical, useful MCP servers that can power AI agents and other applications. In the next section, you will get hands-on practice by defining and using your own tools for the shopping list service. This will help you solidify your understanding and prepare you for more advanced integrations in future lessons.