Developing a MCP Server for a Shopping List Service

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:

class ShoppingListService:
    """Manages a collection of shopping items with basic operations."""
    
    def __init__(self):
        # Initialize the shopping list with some default items
        self.items = [
            {"id": str(uuid.uuid4()), "name": "Milk", "quantity": 2, "purchased": True},
            # ... more items ...
        ]
    
    def get_items(self, purchased=None):
        """Get all items, optionally filtered by completion status."""
        # ... implementation ...
    
    def add_item(self, name, quantity):
        """Add a new item to the shopping list and return its ID."""
        # ... implementation ...
    
    def remove_item(self, item_id):
        """Remove an item from the shopping list by its ID."""
        # ... implementation ...
    
    def set_purchased(self, item_id, purchased=True):
        """Mark an item as purchased or not purchased by its ID."""
        # ... implementation ...

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.

from mcp.server.fastmcp import FastMCP
from shopping_list import ShoppingListService

# Create an MCP server
mcp = FastMCP(
    name="Shopping List",
    description="Provides tools to manage a shopping list: add items, remove items, mark purchased, and list items"
)

# Create a shopping list service
shopping_list = ShoppingListService()

# Define MCP tools...

if __name__ == "__main__":
    # Run the server with the desired transport
    mcp.run(transport="stdio") 

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.

@mcp.tool()
def fetch_items(purchased: bool = None) -> list:
    """
    Retrieve all shopping list items, optionally filtered by purchased status.
    
    Parameters:
        purchased (bool, optional): Filter items by purchased status.
            None returns all items,
            True returns only purchased items,
            False returns only unpurchased items.
    
    Returns:
        list: A list of shopping items matching the filter criteria.
    """
    return shopping_list.get_items(purchased)

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.

@mcp.tool()
def add_item(name: str, quantity: int) -> str:
    """
    Add a shopping list item.
    
    Parameters:
      name (str): The name of the item.
      quantity (int): The quantity to add.
      
    Returns:
      str: The unique ID of the newly added item.
    """
    return shopping_list.add_item(name, quantity)

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.

@mcp.tool()
def remove_item(item_id: str) -> bool:
    """
    Remove an item from the shopping list.
    
    Parameters:
      item_id (str): The unique ID of the item.
      
    Returns:
      bool: True if the item was removed successfully; otherwise False.
    """
    return shopping_list.remove_item(item_id)

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.

@mcp.tool()
def mark_purchased(item_id: str, purchased: bool = True) -> bool:
    """
    Mark an item as purchased or not.
    
    Parameters:
      item_id (str): The unique ID of the item.
      purchased (bool, optional): True to mark as purchased; False otherwise. Defaults to True.
      
    Returns:
      bool: True if the update succeeded; otherwise False.
    """
    return shopping_list.set_purchased(item_id, purchased)

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:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["mcp_server.py"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            # You can now interact with the server using the session object

if __name__ == "__main__":
    asyncio.run(main())

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:

# List all tools exposed by the server
tools_list = await session.list_tools()

# For each tool, display its name, description, and input schema
for tool in tools_list.tools:
    print(f"Name: {tool.name}")
    print(f"Description: {tool.description}")
    print(f"Input Schema:\n{tool.inputSchema}\n")

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

Name: add_item
Description: 
    Add a shopping list item.
    
    Parameters:
      name (str): The name of the item.
      quantity (int): The quantity to add.
      
    Returns:
      str: The unique ID of the newly added item.
    
Input Schema:
{'properties': {'name': {'title': 'Name', 'type': 'string'}, 'quantity': {'title': 'Quantity', 'type': 'integer'}}, 'required': ['name', 'quantity'], 'title': 'add_itemArguments', 'type': 'object'}

...

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:

# Add a new item to the shopping list
response_add = await session.call_tool(
    "add_item",
    {
        "name": "Bananas",
        "quantity": 3
    }
)

# Extract and print the ID of the newly added item
added_id = response_add.content[0].text
print(f"Added item ID: {added_id}")

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

Added item ID: 9322bc54-588d-4855-a440-697627e427fc

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

# Retrieve all shopping list items
response_fetch = await session.call_tool("fetch_items", {})

# Print each item in the shopping list
print("Current shopping list items:")
for item in response_fetch.content:
    print(item.text)

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

Current shopping list items:
{"id": "cb9abd6a-ff42-4808-8552-e664221d5e00", "name": "Milk", "quantity": 2, "purchased": true}
{"id": "06a2fa28-56d9-416a-bc17-3b70bf0107e4", "name": "Bread", "quantity": 1, "purchased": false}
{"id": "59f0f8f2-9309-4a3b-aedb-876faf1653b5", "name": "Eggs", "quantity": 12, "purchased": true}
{"id": "493afcc2-d018-4a9f-b3e7-bf05015b7243", "name": "Apples", "quantity": 6, "purchased": false}
{"id": "8c843bf2-0bb5-402e-85e3-c5aba4e652f4", "name": "Coffee", "quantity": 1, "purchased": false}
{"id": "1e93cfe9-a5f1-483d-b958-09844647e25b", "name": "Bananas", "quantity": 3, "purchased": false}

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.