Case Study: Building a Minimal Notes API with MCP, FastMCP, and n8n

A minimal but complete microservice demonstrating the power of the Model Context Protocol (MCP) for composable tool design.

Project Overview

This project serves as a practical case study in building modern agents and microservices using the Model Context Protocol (MCP). It implements a fully functional Notes API that allows users to create, retrieve, and delete notes.

Unlike traditional REST APIs built with heavy frameworks, this system uses FastMCP to create an MCP Server that defines tools, and n8n acting as the MCP Client to consume them. The result is a clean, modular architecture where business logic is decoupled from the orchestration layer.

Key Technologies

• Python & FastMCP: For defining the core business logic and running the MCP Server.
• n8n: The MCP Client that connects to the server and exposes its tools to the outside world via webhooks.
• JSON Persistence: A lightweight, file-based storage system for data durability.

🏗️ Architecture

The system follows a standard MCP Client-Server architecture:

graph LR
    User[External User] -->|HTTP POST/GET| n8n["n8n (MCP Client)"]
    n8n -->|MCP Protocol| Server[FastMCP Server]
    Server -->|Read/Write| DB[(notes.json)]

1. The MCP Server (Python):

   • Defines three atomic tools: add_note, get_my_notes, delete_note.
   • Handles data validation and lightweight persistence.
   • Run independently and waits for connections from an MCP Client.

2. The MCP Client (n8n):

   • Connects to the Python server using the MCP protocol.
   • Discovers the available tools (add_note, etc.) automatically.
   • Acts as the gateway, triggering these tools via webhooks when external, non-MCP requests come in.

3. Persistence Layer:

   • Uses a local notes.json file.
   • Automatically reloads state on startup.
   • Ensures ID consistency across restarts.

🛠️ Tools & Workflows

Here is how each tool is implemented in Python (Server) and consumed in n8n (Client).

1. Add Note

The Server Code (Python):

@mcp.tool()
def add_note(content: str) -> str:
    """Add a new note for a user"""
    global ID_COUNTER
    note_id = ID_COUNTER
    ID_COUNTER += 1

    NOTES.append({
        "id": note_id,
        "content": content,
        "created_at": datetime.utcnow().isoformat()
    })
    save_notes_to_disk()
    return f"added note #{note_id}: {content}"

The Client Workflow (n8n): Accepts a webhook POST, calls the add_note tool, and returns the confirmation.

2. Get Notes

The Server Code (Python):

@mcp.tool()
def get_my_notes() -> str:
    """Get all notes for a user"""
    if not NOTES:
        return "no notes yet"

    lines = []
    for note in NOTES:
        lines.append(f'{note["id"]}. {note["content"]} (at {note["created_at"]})')
    return "\n".join(lines)

The Client Workflow (n8n): Accepts a webhook GET, calls get_my_notes, and returns the list.

3. Delete Note

The Server Code (Python):

@mcp.tool()
def delete_note(note_id: int) -> str:
    """Delete a note by its id"""
    for note in NOTES:
        if note["id"] == note_id:
            NOTES.remove(note)
            save_notes_to_disk()
            return f"deleted note #{note_id}"

    return f"note #{note_id} not found"

The Client Workflow (n8n): Accepts a webhook POST with an ID, calls delete_note, and confirms deletion.

🚀 Getting Started

To run this project locally, you will need Python (managed by uv is recommended) and an instance of n8n.

Prerequisites

• Python 3.10+
• uv (for dependency management)

Installation

1. Clone the repository:

   git clone https://github.com/Start-Faking-It/mcp-notes-api.git
   cd mcp-notes-api
   

2. Install dependencies:

   uv sync
   

3. Run the Server:

   uv run main.py
   

   The server will start on port 8000 (default for the HTTP transport configuration in main.py).

🧠 Lessons Learned

This project highlights several advantages of the MCP approach:

• Tool Reusability: The same add_note function could be used by an LLM agent, a CLI, or a wacky n8n workflow without changing a single line of code.
• Simplified Backend: We usually write 50% of our code just handling API schemas and router boilerplate. MCP abstracts that away.
• State Management: Even simple persistence requires care (reloading IDs, file locking). Separating this from the API layer made testing much easier.

License

MIT