Copy page

Guides

Simple MCP Server

This example demonstrates how to build a minimal custom MCP (Model Context Protocol) server from scratch using FastMCP 2.0.

This is a great starting point for building your own custom MCP servers with business-specific tools and logic.

Running on Unikraft Cloud

To run this MCP server on Unikraft Cloud:

1. Install the CLI and a container runtime engine, for example Docker. Use the unikraft CLI or the legacy kraft CLI.

2. Clone the examples repository and cd into the examples/mcp-server-simple/ directory:

Code
git clone https://github.com/unikraft-cloud/examples
cd examples/mcp-server-simple/

Make sure to log into Unikraft Cloud and pick a metro close to you. This guide uses fra (Frankfurt, 🇩🇪):

When done, invoke the following command to deploy this app on Unikraft Cloud:

The output shows your instance details:

Code
[●] Deployed successfully!
 │
 ├────── name: mcp-server-simple-bbdcb
 ├────── uuid: e87d3591-3497-4f30-bd76-1dc886059647
 ├───── metro: https://api.fra.unikraft.cloud/v1
 ├───── state: running
 ├──── domain: https://cool-paper-b6mht7jv.fra.unikraft.app
 ├───── image: mcp-server-simple@sha256:cbbfb441ee313a6c7c0de571e9002f0f6031312e203ffb6be3b8f4950df3bc20
 ├─ boot time: 145.96 ms
 ├──── memory: 512 MiB
 ├─── service: cool-paper-b6mht7jv
 ├ private ip: 10.0.0.193
 └────── args: /usr/bin/python3 /src/server.py

In this case, the instance name is mcp-server-simple-bbdcb and the service cool-paper-b6mht7jv. They're different for each run.

For testing, you can use the example client included in this directory. First, install uv if you haven't already, then run:

Code
export MCP_SERVER_URL=https://cool-paper-b6mht7jv.fra.unikraft.app/mcp
uv run client.py

Code
Connecting to https://cool-paper-b6mht7jv.fra.unikraft.app/mcp...

--- Listing Tools ---
Name: get_weather
Description: Get current weather for a city.

Args:
    city: Name of the city

Returns:
    Weather information including temperature, conditions, and humidity

Name: get_time
Description: Get current time in a timezone.
...

You can list information about the instance by running:

Code
NAME                     FQDN                                  STATE    STATUS   IMAGE                                               MEMORY   VCPUS  ARGS                             BOOT TIME
mcp-server-simple-bbdcb  cool-paper-b6mht7jv.fra.unikraft.app  standby  standby  mcp-server-simple@sha256:cbbfb441ee313a6c7c0de5...  512 MiB  1      /usr/bin/python3 /src/server.py  9.15 ms

When done, you can delete the instance with:

Code
kraft cloud instance remove mcp-server-simple-bbdcb

Available tools

This MCP Server provides the following tools:

• get_weather: Get simulated weather for a city
• get_time: Get current time in a timezone
• calculate: Perform basic arithmetic operations (add, subtract, multiply, divide)

Building your own tools

This example shows the basic structure of an MCP server using FastMCP. To add your own tools:

1. Define the tool using the @mcp.tool() decorator:

   • Add type hints for parameters
   • Include a docstring describing what the tool does
   • Parameters are automatically converted to JSON schema

2. Write the tool function:

   • Process the parameters
   • Return a string result (or raise an exception for errors)

3. Test locally before deploying:

   Code
   pip install -r requirements.txt
   python server.py

Example:

Code
from fastmcp import FastMCP

mcp = FastMCP("My Custom Server")

@mcp.tool()
def my_custom_tool(param1: str, param2: int) -> str:
    """Description of what this tool does.

    Args:
        param1: Description of first parameter
        param2: Description of second parameter

    Returns:
        Result description
    """
    # Your implementation here
    return f"Processed {param1} with {param2}"

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8080)

Architecture

The server uses FastMCP, a high-level framework for building MCP servers that features:

• HTTP Transport: Built-in Streamable HTTP transport
• Type-Safe: Automatic JSON schema generation from Python type hints
• Simple API: Decorator-based tool definitions

This provides:

• Standard MCP protocol support
• Automatic tool schema generation
• Built-in HTTP server
• Easy deployment to any platform

Learn more

• MCP Documentation
• FastMCP documentation
• Building MCP Servers
• Unikraft Cloud Documentation
• Building Dockerfile Images with Buildkit

Use the --help option for detailed information on using Unikraft Cloud:

Or visit the CLI Reference or the legacy CLI Reference.