Minimal MCP Server Example (fastmcp)

This repo is a minimal, working MCP server example exposing two tools via fastmcp:

• echo(text): returns text unchanged
• now(utc=True): returns current time in ISO 8601

It’s designed as a small, copy‑pasteable starting point.

Contents

• server.py: minimal MCP server with two tools
• Dockerfile: container image for running the server
• requirements.txt: Python dependency list

Prerequisites

• Python 3.11+ (3.12 recommended) or Docker

Run Locally (Python)

python -m venv .venv
source .venv/bin/activate   # Windows (PowerShell): .venv\\Scripts\\Activate.ps1
pip install -r requirements.txt
python server.py

Run with Docker

Build the image (tag matches the example config below):

docker build -t mcp-basic:latest .

Run it (stdio transport):

docker run --rm -i mcp-basic:latest

Codex CLI / MCP Client Config

Configure your Codex MCP client (e.g., ~/.codex/config.toml) with either Docker or direct Python.

Docker-based (uses the image built above):

[mcp_servers.basic]
command = "docker"
args = ["run", "--rm", "-i", "mcp-basic:latest"]
# optional env passthrough:
# env = { "EXAMPLE_API_KEY" = "..." }

Direct Python (runs from your checkout):

[mcp_servers.basic]
command = "python"
args = ["server.py"]
# Optionally set working directory if needed:
# workingDirectory = "/path/to/repo"

How It Works

• The server is defined in server.py and uses fastmcp.FastMCP("basic") with stdio transport.
• Tools are registered via @mcp.tool decorators and exposed to the client.

Extending

• Add new tools by defining functions with type hints and decorating with @mcp.tool.
• Keep the interface simple and return JSON-serializable values.

Troubleshooting

• If the client can’t start the server, verify fastmcp is installed (pip show fastmcp).
• For Docker, ensure the image is built (docker images | grep mcp-basic) and that docker run --rm -i mcp-basic:latest works.

License

None specified; use as an example and adapt as needed.