Building a Scalable FastAPI Server for Diverse Tools

Hello! Welcome back.

In the last module, you successfully navigated a complex, multi-step refactoring task, culminating in updating the test suite to validate the new asynchronous code. You demonstrated a robust, professional workflow for AI-assisted development.

Now, we pivot from modifying existing code to architecting new capabilities. This module, Advanced MCP Server Integration, is where you'll build the custom infrastructure to supercharge your Claude Code workflows. Our first learning outcome is to architect an extensible MCP server with FastAPI designed to host multiple stateful and stateless tools.

This lesson moves beyond the basics of creating a single tool. We'll focus on the architectural decisions required to build a robust, scalable platform capable of hosting a diverse suite of tools—some that are simple, fire-and-forget functions (stateless), and others that need to remember context across multiple interactions (stateful).

The Big Picture: Your MCP Server as an Intelligent Gateway

An MCP server acts as an intelligent gateway, translating high-level requests from an AI agent into concrete actions on your backend systems. Before we dive into the design patterns, let's visualize where our server fits into the ecosystem.

We are building a remote server that can be accessed by any MCP client, like Claude Code. This server will become a central hub for your custom tools, making them available wherever you're working.

The Core Architectural Challenge: Managing State

The most critical decision when architecting an MCP server is how to handle state. A stateless tool is simple: it receives a request, performs an action, and returns a response, forgetting everything immediately. A calculator tool is a perfect example.

A stateful tool, however, must maintain context across multiple calls. Imagine a tool for querying a large dataset. The first call might connect to the data source, the second might apply a filter, and a third might perform an aggregation. The tool needs to remember the connection and the filter from previous steps.

This requirement for memory, or "state," is fundamental to building powerful agentic workflows. A fantastic technical article from Zeo, "MCP Server Architecture," provides a blueprint for thinking about this problem. It introduces three models for state management.

As you can see from the reading, while multiple patterns exist, the Server-Side State Cache model is often the most practical and secure starting point for building sophisticated, stateful tools. It gives the server full control over the conversational context. For our purposes, we can think of your PostgreSQL database as a more persistent, structured version of this state cache.

Practical Implementation Patterns with FastAPI

Now let's translate this architectural theory into practice using FastAPI. Your experience with FastAPI will be a great asset here.

Distinguishing Stateful and Stateless Connections

The MCP protocol itself has evolved to better handle the distinction between stateful and stateless interactions. The modern streamable HTTP transport is more flexible than the older SSE (Server-Sent Events) transport.

This first video provides a clear, concise demonstration of how this works in fastmcp, the library we'll be using.

This shows that you can decide at the server level whether you want to enforce session management for all tools or allow simple, one-off calls. For an extensible server hosting both types of tools, enabling stateless HTTP is generally preferable as it provides maximum flexibility. You can then build state management into specific tools that need it.

Structuring a Multi-Tool Server

Now, let's look at the structure for hosting multiple tools and implementing a stateful tool using a database—a perfect real-world example of the "Server-Side State Cache" pattern.

This video demonstrates the key architectural pattern for our extensible server:

1. A single FastAPI application serves as the host.
2. Stateless tools can be simple functions decorated with @mcp.tool that take input and return output.
3. Stateful tools are also functions decorated with @mcp.tool, but they contain logic to read from and write to a persistent store (like your PostgreSQL database) using a unique identifier (like a user ID or session ID) to retrieve the correct context for the current interaction.

This architecture is highly extensible. To add a new stateless tool, you just add a new decorated function. To add a new stateful tool, you define its data model in your database and add a new decorated function that interacts with that model.

Your Architectural Blueprint

Based on these principles, here is a blueprint for your extensible MCP server:

1. Framework: Use FastAPI as the web server and fastmcp for the MCP implementation.
2. Transport: Use streamable HTTP, configured for stateless connections (stateless_http=True) to allow maximum flexibility.
3. Tool Definition: Define each tool as a separate Python function decorated with @mcp.tool. The function's name, docstring, and typed parameters will automatically become the tool's definition for Claude.
4. State Management:
   • For stateless tools (e.g., a code formatter, a simple calculator), the function will perform its logic and return a result without any database interaction.
   • For stateful tools (e.g., a database query builder, a multi-step refactoring assistant), the function will connect to your PostgreSQL database (using SQLAlchemy or asyncpg). It will use a session identifier passed into the tool to store, retrieve, and update state across multiple calls.
5. Extensibility: Place tools in separate Python modules (e.g., tools/database_tools.py, tools/file_tools.py) and import them into your main FastAPI application. This keeps the project organized and makes it easy to add or remove functionality.

Conclusion

You now have a solid architectural foundation for building an advanced MCP server. We've moved from abstract concepts to a concrete, actionable blueprint tailored to your skills and goals.

Key Takeaways:

• State management is the central architectural decision. The Server-Side State Cache (using your database as a persistent store) is a robust and secure pattern for building complex tools.
• An extensible MCP server can host both stateful and stateless tools. You can choose the right implementation for each tool's needs.
• Using FastAPI with fastmcp provides a modern, high-performance stack for building these servers.
• The key to a stateful tool is using a unique identifier (like a user or session ID) to link successive calls to the correct data in your persistent store.

Next Up:
With the architecture defined, our next step is to get our hands dirty. In the next lesson, you will implement and expose a stateful tool in a custom MCP server that maintains context across multiple calls. We will build on the database pattern from today's lesson to create a tool that can remember and build upon previous interactions within a single conversation.