Creating an MCP Server Using FastMCP: A Comprehensive Guide

Building AI applications that can seamlessly access your data and tools is surprisingly challenging. The Model Context Protocol (MCP) solves this problem by standardizing how LLMs connect to external resources. Think of MCP like a USB-C port for AI applications - a universal connector that lets your language models plug into different data sources and tools with minimal friction.

FastMCP takes the powerful but complex MCP protocol and makes it accessible through a high-level, Pythonic interface. With just a few decorators, you can transform ordinary Python functions into MCP resources and tools that any MCP-compatible client (like Claude Desktop) can instantly use.

In this guide, we'll walk through creating your own MCP server using FastMCP, giving your AI assistants secure access to your data and custom functionality. Let's get started by building a simple server that can power your AI workflows.

What is an MCP Server?

An MCP server is a lightweight program that exposes your data and functionality to language models through the standardized Model Context Protocol. These servers act as bridges between AI applications (like Claude Desktop or other LLM-powered tools) and your local data sources or remote services.

At its core, an MCP server offers six main capabilities:

1. Resources: Read-only endpoints that provide data to LLMs (similar to GET requests in web APIs)
2. Tools: Functional endpoints that execute actions when called by an LLM (like POST/PUT endpoints)
3. Prompts: Reusable templates that guide how LLMs interact with your server
4. Sampling: The ability to request completions from the connected LLM. This basically means that if the server requires an LLM to complete it's own action (for example creating a summary), the server can request the client to execute the LLM completion (so that the client pays for the completion and can control which LLM is used (think of data privacy)).
5. Transports: Communication mechanisms that enable clients and servers to exchange messages, such as stdio (Standard Input/Output) for local tools and SSE (Server-Sent Events) for web-based applications
6. Roots: URI-based boundaries that define where servers can operate, allowing clients to inform servers about relevant resource locations (like file paths or API endpoints)

MCP servers operate within a client-server architecture where:

• Your MCP server runs locally or on your infrastructure
• MCP clients (like Claude Desktop) connect to your server
• Your server provides secure access to your files, databases, APIs, or custom functionality

Unlike traditional web APIs, MCP servers are specifically designed for LLM interactions, with features for natural language understanding, context management, and LLM-specific functionality baked in.

By creating an MCP server, you enable AI assistants to interact with your data and services while keeping your information secure and within your control. No need to upload sensitive documents to third-party services or rebuild integrations for each new AI tool.

General MCP Server idea

MCP Server Example

If the above description is too abstract, let's discuss a simple example. Github offers an MCP Server, which in terms offers various tools to interact with Github, for example there are tools to get repository information or tools to create pull requests.

As many AI chat tools nowadays already provide an MCP client implementation, all these tools can now connect to Github and create AI-powered workflows. This is sort of a win-win situation: All these tools don't need to integrate the Github API (and as a matter of fact many, many other APIs), but they simply implement the MCP Client. As the MCP protocol allows LLMs to intelligently read the available tools, they automatically are aware about all the available tools ("API endpoints", if you will).

What's the difference between MCP servers and an API

As we already established, MCP servers - at their core - are just standardized APIs. So why not use the millions of existing APIs out there? The simple answer is: MCP servers make it easy for LLMs to discover what tools and resources are available in this API. Furthermore, they standardize authentication and transport. If enough people agree on MCP being the way forward (and currently it looks like many people agree that this will be the way forward, like Microsoft), Anthropic, Google and OpenAI), we got one single interface which is optimized for LLM discoverability. All client-side tools therefore only need to implement the MCP client, all the rest is handled by the protocol and the LLMs using the MCP client. Note that the MCP protocol in itself only really makes sense when you have LLMs which can "read" the provided resources/tools and then act upon them.

If you simply need to call APIs, ordinary REST endpoints are still the way to go.

One other further advantage of MCP servers: As the protocol seems to be widely adopted by AI client tools, you can also create a local MCP server to provide controlled and secure access to resources on your system. For example allow file-system access, but only on a certain file mount.

What is FastMCP?

FastMCP is a high-level Python framework that dramatically simplifies the process of building MCP servers. While the raw MCP protocol requires implementing server setup, protocol handlers, content types, and error management, FastMCP handles all these complex details for you.

At its heart, FastMCP provides a decorator-based API that transforms regular Python functions into MCP-compatible tools, resources, and prompts. The framework's key advantages include:

1. Minimal Boilerplate: Create fully-functional MCP servers with just a few lines of code.
2. Intuitive Design: The decorator pattern will feel familiar to developers who've used frameworks like Flask or FastAPI.
3. Automatic Schema Generation: FastMCP uses type hints and docstrings to automatically generate the necessary MCP schemas without manual configuration.
4. Pydantic Integration: Leverage Pydantic models for complex inputs and outputs with automatic validation.
5. Async Support: Built-in support for both synchronous and asynchronous function handlers.
6. Transport Abstraction: Work with various communication protocols (stdio, SSE, WebSockets) without changing your application code.
7. Context Object: Access server capabilities, log information, report progress, and even request LLM sampling through an intuitive context object.
8. Client Implementation: Includes a full client implementation for testing your servers programmatically.

FastMCP's primary goal is to make MCP development accessible to Python developers of all skill levels while still exposing the full power of the protocol. The framework handles all the low-level protocol details, allowing you to focus on implementing your business logic rather than wrestling with the complexities of the MCP specification.

With FastMCP, you can go from concept to working MCP server in minutes rather than hours, making it the ideal choice for rapidly prototyping AI-powered tools or building production-ready MCP services.

Hands on: Building an MCP server using FastMCP

Now that we know what we need to know, let's dive in. We're going to build a simple MCP server which allows to:

• Fetch a users profile (Resource)
• Update a document on the server (Tool)
• Add progress reporting (Context)

Prerequisites: Basic MCP Server setup

First, let's create a virtual environment and install fastmcp (this also contains the mcp dependencies).

1uv venv
2source .venv/bin/activate
3uv pip install fastmcp

Then, let's create the basic server instantiation:

1from fastmcp import FastMCP
2
3mcp = FastMCP(
4    name="Document Assistant",
5    instructions="This server allows to fetch and update documents related to PONDHOUSE DATA DOCS."
6)
7
8if __name__ == "__main__":
9    mcp.run()

This snipped will run an MCP server (without any resources yet) with STDIO transport mode. What does this mean:

• The client starts a new server process for each session
• Communication happens through standard input/output streams
• The server process terminates when the client disconnects
• This is ideal for integrations with local tools like Claude Desktop, where each conversation gets its own server instance

FastMCP Transports explained

Above, we created our first little MCP server (which doesn't do anything yet). However, we learned that this server runs with STDIO transport. This, for obvious reasons, means that this server is mainly used to provide access to resources local to your system. While there are many use cases for that, we think the main advantage of MCP servers lies in providing a remote-accessible resource to allow controlled and secure access to your internal systems. Therefore, FastMCP offers a second transport: SSE Transport (Server Sent Events).

To use this transport, simple use:

1mcp.run(transport="sse", host="0.0.0.0", port=8000)

This will spawn a server listening on all interfaces and port 8000.

We'll use this transport forward.

Creating an MCP Resource using FastMCP

Resources offer read-only access to internal data and information. Resources are requested by providing a URI (which if often AI generated on the client-side). The FastMCP uses this URI to find the requested resource, looks for the data somewhere in it's environment and then returns them to the client.

Defining a Resource is rather simple.

1. Create a python function which returns the data you want your resource to return.

2. Add a fastmcp resource decorator with the unique URI of this resource as parameter.

3. Optionally add additional metadata, like description or tags.

   Note: These additional metadata can be used by clients for filtering or deciding which resource to call. As with any LLM-based application these metadata are rather important that the (client)-AI knows what to do. So we mostly recommend always using all the meta-information.

   These metadata are available:

   • uri: The unique identifier for the resource (required).
   • name: A human-readable name (defaults to function name).
   • description: Explanation of the resource (defaults to docstring).
   • mime_type: Specifies the content type (FastMCP often infers a default like text/plain or application/json, but explicit is better for non-text types).
   • tags: A set of strings for categorization, potentially used by clients for filtering.

1from fastmcp import FastMCP
2
3mcp = FastMCP(
4    name="Document Assistant",
5    instructions="This server allows to fetch and update documents related to PONDHOUSE DATA DOCS."
6)
7
8@mcp.resource(
9    uri="data://application-information",
10    name="ApplicationInfo",
11    description="Provides general runtime-information about the application",
12    mime_type="application/json",
13    tags={"status", "observability"}
14)
15async def get_application_status() -> dict:
16    """Function description - ignored if set via decorator description parameter"""
17
18    # TODO: Implement any logic here. Eg. database call or request status
19    # information from your monitoring system.
20
21    return {
22          "app_id": 123,
23          "status": "running",
24          "started_at": "2025-04-27 10:23:00"
25     }

To summarize what we have so far: By providing the uri data://application-information, a client can get the defined application status report. So good so far. Now we want to implement returning a user profile. The problem: We currently don't have the option to pass the user id to the MCP server, right? As we only have the URI to exchange data.

This is where resource templates come into play.

MCP Resource templates

Resource templates are simply a way to tell the MCP server, that parts of the URI path in the resource defintion is dynamic. Eg. we can define the following URI to implement our user-profile resource: data://user-profile/{user_id}. The resource function than simply takes an additional parameter for the dynamic value.

1@mcp.resource(
2    uri="data://user-profile/{user_id}",
3    name="UserProfile",
4    description="Gets the user profile information for user_id",
5    mime_type="application/json",
6    tags={"user"}
7)
8async def get_user_profile(user_id: str) -> dict:
9    """Gets the user profile information for user_id"""
10
11    # TODO: Implement any logic here. Eg. database call or request profile
12    # information from your user auth system.
13
14    return {
15      "user_id": 1234,
16      "user_name": "Hans Maier",
17      "email": "hans@maier.com"
18     }

Perfect, now the clients simply use the resource alongside a dynamic user_id parameter.

Creating an MCP Tool using FastMCP

Tools are, in short, the most important parts of any AI agent systems. Tools are functions which allow the AI the "interact" with the external world. Let's say you have a function which makes a database call. You transform this function to a tool, allowing the AI to call this function and therefore access your database.

For an in-depth introduction into what tools are, we highly recommend our AI Agents from scratch article.

Now, similarly to resources, with FastAPI we don't really need to care about the underlying protocol or who calls what. Just create our function, which executes something, add a decorator and optionally add some metadata parameter.

FastMCP:

• Uses the functions name as tool name. Make it descriptive.
• Uses the docstring (or the decorator description param) as tool description.
• Uses type-annotations for schema generation.
• Validates the incoming data based on this type schema.

Again, make sure you make your tools async, if they require waiting tasks.

1@mcp.tool()
2async def edit_file(filename: str, line: str) -> None:
3    """
4    Asynchronously appends a line of text to the end of a file.
5    """
6    try:
7        async with aiofiles.open(filename, mode='a') as file:
8            if not line.endswith('\n'):
9                line += '\n'
10            await file.write(line)
11    except Exception as e:
12        print(f"Error appending to file: {str(e)}")
13        raise

Adding parameter metadata

Everyone who created AI agents (or clients) in the past knows, that the most important aspect of creating tools is actually the tool description, and more so the tool parameter description. So that the AI knows, which parameters to provide.

For that, FastMCP allows to use the pydantic Annotated field to add more information to the parameters.

Furthermore, parameters with default values are communicated as optional.

1@mcp.tool()
2async def edit_file(
3    filename: Annotated[ str, Field( description="Path to the target file", min_length=1, max_length=255) ],
4    line: Annotated[ str, Field( description="Text content to append to the file", min_length=1) ],
5    second_line: Annotated[ str, Field( description="Optional second line to append to the file", min_length=1), ] = ""
6    ):
7    """
8    Asynchronously appends a line of text to the end of a file.
9    """
10    try:
11        async with aiofiles.open(filename, mode='a') as file:
12            if not line.endswith('\n'):
13                line += '\n'
14            await file.write(line)
15
16            if second_line:
17                if not second_line.endswith('\n'):
18                    second_line += '\n'
19                await file.write(second_line)
20    except Exception as e:
21        print(f"Error appending to file: {str(e)}")
22        raise

Error handling with FastMCP tools

Now the final piece of the puzzle, how do we communicate errors with the AI? Most of the time you want to inform the AI that there was an error executing a tool, so that they can decide to run the tool differently or use a different one.

Luckily, this is very easy in FastMCP: Simply throw a standard python Exception, like we did above.

FastMCP converts the exception into an MCP error response, which is sent back to the client. The client can then decide what to do with the error, but mostly they will want to redirect it to the LLM for further action taking.

Supported types with FastMCP tools

For tool input parameters, FastMCP basically supports most of the types which are also supported by pydantic. This includes, but is not limited, to all built-in types, dates, literals, enums, collections (dicts, lists), uuids, complex pydantic models and many more. For a complete list, please visit the FastMCP docu

For output types, we are a bit more limited. These are the supported output (return) types:

• str: Sent as TextContent.
• dict, list, Pydantic BaseModel: Serialized to a JSON string and sent as TextContent.
• bytes: Base64 encoded and sent as BlobResourceContents (often within an EmbeddedResource).
• fastmcp.Image: A helper class for easily returning image data. Sent as ImageContent.
• None: Results in an empty response (no content is sent back to the client).

Implement MCP server progress reporting using FastMCP Context

The FastMCP Context allows to access the underlying MCP session or to access your MCP servers capabilities. Examples for that are:

• Logging: Send log messages from your MCP server back to the client.
• Accessing Resources: In your MCP server tools, you might want to access already defined resources. Eg. get the file-path from a resource.
• Progress reporting: Send progress update to the client for long-running operations.

There are more advanced context options available, which are not in scope for this article. Feel free to read up on them here. We'll also provide an article about them in the near future.

For our small project, we are going to implement progress reporting, to showcase the Context feature.

Again, very simple to do:

1. To the function (resource or tool) where you want to access the context, simply add a parameter ctx of type Context (the name does not matter, the type-hint Context needs to be provided though).

2. Then simply use the ctx.report_progress(progress, total) method to send progress back to the client.

1from fastmcp import FastMCP, Context
2
3mcp = FastMCP(
4    name="Document Assistant",
5    instructions="This server allows to fetch and update documents related to PONDHOUSE DATA DOCS."
6)
7
8@mcp.tool()
9async def edit_file(
10    filename: Annotated[ str, Field( description="Path to the target file", min_length=1, max_length=255) ],
11    ctx: Context,
12    line: Annotated[ str, Field( description="Text content to append to the file", min_length=1) ],
13    second_line: Annotated[ str, Field( description="Optional second line to append to the file", min_length=1), ] = ""
14    ):
15    """
16    Asynchronously appends a line of text to the end of a file.
17    """
18    await ctx.info(f"Analyzing {len(data)} data points")
19    try:
20        async with aiofiles.open(filename, mode='a') as file:
21            if not line.endswith('\n'):
22                line += '\n'
23            await file.write(line)
24            if second_line:
25                await ctx.report_progress(progress=50, total=100)
26                if not second_line.endswith('\n'):
27                    second_line += '\n'
28                await file.write(second_line)
29
30            await ctx.report_progress(progress=100, total=100)
31    except Exception as e:
32        print(f"Error appending to file: {str(e)}")
33        raise

That's it.

Testing your MCP server

Now that we've created ourselves an MCP server, we need to run it. As outlined, FastMCP already packages uvicorn, so simply run your python file. If you followed this guide, the server will use the SSE transport and listen on port 8000.

Either use a tool like Claude Desktop or create a simple MCP client and test the capabilities.

1from fastmcp.client import Client
2import asyncio
3
4# Note the `sse` path post-fix for sse servers
5# For all transports, see https://gofastmcp.com/clients/client#transports
6sse_url = "http://localhost:8000/sse"
7
8client = Client(sse_url)
9
10
11async def main():
12    # Connection is established here
13    async with client:
14        print(f"Client connected: {client.is_connected()}")
15
16        tools = await client.list_tools()
17        print(f"Available tools: {tools}")
18
19        if any(tool.name == "edit_file" for tool in tools):
20            result = await client.call_tool(
21                "edit_file",
22                {
23                    "filename": "hello-world.txt",
24                    "line": "This text will be added to the file.",
25                },
26            )
27            print(f"Greet result: {result}")
28
29    # Connection is closed automatically here
30    print(f"Client connected: {client.is_connected()}")
31
32
33if __name__ == "__main__":
34    asyncio.run(main())

For a fill reference of available client methods for the FastMCP client, see their documentation

Wrapping up

In this article we've built ourselves a fully-fledged MCP server, providing tools, resources and status reports to any connected clients. Using this server any client implementing the MCP protocol now can connect to our tool - basically offering a universal way for allowing AI clients to interact with our tools and servers.

Further reading

• Smolagents: Minimal Agent Framework: Explore a lightweight approach to agent development
• Langfuse: The Open Source Observability Platform: Monitor and improve your LLM applications
• Evaluate RAG Performance Using RAGAS: Learn how to measure and optimize your retrieval systems
• High-Quality AI Agent Systems: Best practices for building robust AI agents

Interested in how to train your very own Large Language Model?

We prepared a well-researched guide for how to use the latest advancements in Open Source technology to fine-tune your own LLM. This has many advantages like:

• Cost control
• Data privacy
• Excellent performance - adjusted specifically for your intended use