mcp_training

MCP server with weather, geocoding, and currency tools, and a console client that converses with an OpenAI model capable of using them.

Tú › ¿Qué tiempo hace en Madrid?

Modelo:
  En Madrid hay 24,3 °C, humedad del 41 % y cielo despejado.

  · get_lat_lon_from_city → get_current_weather

How it works

main_client.py ──> OpenAI (Responses API) ──> [túnel] ──> main_server.py (MCP)
   tu terminal        el modelo decide                     5 herramientas
                      qué herramientas usa                 sobre APIs públicas

The client does not execute the tools: it passes the public URL of the MCP server to OpenAI, and it is OpenAI that lists, calls, and chains them (city → coordinates → weather). That is why the server must be accessible from the internet: OpenAI connects from its servers, not from your machine.

Tools

Weather and geocoding use Open-Meteo (free, no key). Currency uses ExchangeRate-API, which does require a key, and supports 20 currencies (/monedas in the CLI).

Structure

config/settings.py     configuración y logging (todo sale del .env)
server/                herramientas + clientes HTTP de las APIs externas
client/                cliente de OpenAI + interfaz de terminal
main_server.py         arranca el servidor MCP
main_client.py         arranca la conversación

Related MCP server: Python Weather MCP Server

Installation

Requires Python 3.11+. With uv (recommended):

git clone <url-del-repo>
cd mcp_training
uv sync

Or with pip and a virtual environment:

python -m venv .venv
.venv\Scripts\activate        # Windows;  en Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

Configuration

Copy the example and fill in your keys:

cp .env.example .env

Only two variables are mandatory:

And a third one, MCP_PUBLIC_URL, which is filled in the next step. Everything else (model, port, transport, timeouts, log level) has sensible defaults and is documented in .env.example.

Usage

You need three terminals: server, tunnel, and client.

1. Start the MCP server

uv run python main_server.py

It listens on http://127.0.0.1:8002/mcp.

2. Publish the server with a tunnel

OpenAI needs a public URL to reach the server. With devtunnel:

devtunnel port create -p 8002 --allow-anonymous
devtunnel host

Copy the URL it prints (https://xxxxxxx-8002.euw.devtunnels.ms) and put it in the .env:

MCP_PUBLIC_URL=https://xxxxxxx-8002.euw.devtunnels.ms

Any tunnel works (ngrok, Cloudflare Tunnel…); the only thing that matters is that the URL is accessible from outside. The client adds /mcp on its own if it doesn't have it.

3. Launch the client

uv run python main_client.py

Type your query and press Enter. The conversation has memory: after asking about Madrid you can simply say "and tomorrow?".

Convierte 100 USD a EUR
¿Cuál es el clima actual en Madrid?
Dame el pronóstico del tiempo para Nueva York

CLI commands:

Use the server without the client

The server is a standard MCP: it works with any compatible client. To connect it as a subprocess (Claude Desktop, Claude Code…) set MCP_TRANSPORT=stdio in the .env; thus neither the tunnel nor the port are needed.

Common issues

To see the details of each call (arguments, responses, URLs) set LOG_LEVEL=DEBUG in the .env. Logs go to stderr, so python main_client.py > charla.txt saves only the conversation.