vinod-soni-microsoft/ai-agentic-mcp-demo
If you are the rightful owner of ai-agentic-mcp-demo and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The MCP Weather Demo is a simple, end-to-end agent-ready demonstration built on the Model Context Protocol (MCP), showcasing how to expose tools, resources, and prompts that an agent could use.
MCP Weather Demo
A simple, end-to-end agentāready demo built on Model Context Protocol (MCP) ā not an agent by itself:
- A local Python MCP server that exposes weather tools, a resource, and a reusable prompt
- A Python MCP client that spawns the server via stdio and lets you call each capability
- Ready-to-run VS Code tasks and a PowerShell script for quick demos on Windows
The goal is to show how to expose tools/resources/prompts that an agent could use, and how to drive them via a simple CLI.
What this solution does
The MCP server provides:
- Tools
- get_weather(city, unit): Real-time current conditions using OpenāMeteo (geocoding + forecast)
- get_alerts(city): Active warnings using OpenāMeteo Warnings (best-effort, may be empty by region/time)
- Resource
- weather://city/{city}: A quick human-readable snapshot for any city
- Prompt
- weather_report(city): A concise, reusable instruction to turn tool output into a readable summary
The MCP client spawns the server over stdio and offers a CLI to:
- List available tools and prompts
- Call get_weather or get_alerts
- Read the weather resource for a city
- Fetch and display the prompt template
Architecture overview
- Transport: stdio (client launches the server process)
- Data modeling: Pydantic for structured tool outputs
- HTTP client: httpx
- Weather API: OpenāMeteo
- Geocoding: https://geocoding-api.open-meteo.com
- Current weather: https://api.open-meteo.com/v1/forecast
- Warnings: https://api.open-meteo.com/v1/warnings
Prerequisites
- Windows (PowerShell) or any OS with Python 3.10+
- Python 3.10 or newer
- VS Code recommended (tasks included)
Setup
You can use the included VS Code task āInstall dependenciesā, or do it manually:
PowerShell (Windows):
python -m venv .venv
. .venv/Scripts/Activate.ps1
pip install -r requirements.txt
Quick start
Using VS Code tasks (recommended):
- Run āInstall dependenciesā
- Run āRun Client (spawns server)ā to see default output for London
Or run the PowerShell script:
pwsh ./run.ps1
Usage (client CLI)
Activate your venv first, then call the client with an action and city.
. .venv/Scripts/Activate.ps1
# List tools and prompts
python client/client.py --action list
# Get current weather (Celsius)
python client/client.py --city "New Delhi" --unit c --action get_weather
# Get active alerts (if any)
python client/client.py --city "New Delhi" --action get_alerts
# Read the resource
python client/client.py --city "New Delhi" --action resource
# Fetch the reusable prompt
python client/client.py --city "New Delhi" --action prompt
# End-to-end: list + weather + alerts + resource + prompt
python client/client.py --city "New Delhi" --action all
Notes:
- Cities with spaces are handled by the client (URL-encoded for the resource); the server decodes them.
- If geocoding cannot find a place (e.g., misspelling), the tool returns a clear error.
- Alerts are real-time. An empty list means no current warnings for that location or limited coverage in the region.
- The included CLI is a manual driver for demo purposes and does not include an LLM loop.
Is this an agent?
Short answer: No. This repository is agentāready.
- What this repo includes:
- An MCP server that exposes tools (get_weather, get_alerts), a resource (weather://city/{city}), and a reusable prompt (weather_report)
- A simple CLI client that manually calls those capabilities over stdio
- What makes it āagenticā:
- When an LLMādriven client (or agent framework) plans which tool(s) to call, executes them via MCP, and then synthesizes the result using the provided prompt
- How to make it agentic:
- Replace or wrap the CLI with an LLM loop that uses MCP to decide and act (plan ā call tools ā summarize with prompt)
Server capabilities
- get_weather(city, unit)
- Geocodes city ā latitude/longitude
- Fetches current variables: temperature_2m, relative_humidity_2m, wind_speed_10m, weather_code
- Returns structured output with rounded values and a readable condition
- get_alerts(city)
- Geocodes city
- Queries OpenāMeteo Warnings
- Normalizes severity/title/description into a simple format
- Resource: weather://city/{city}
- Quick, human-readable one-liner for current conditions
- Prompt: weather_report(city)
- Returns a single instruction string to guide an LLM in writing a concise weather summary
Project structure
README.md
requirements.txt
run.ps1
client/
client.py
server/
server.py
Troubleshooting
- Permission denied on .venv/Scripts/python.exe
- Close other terminals using the venv and retry the VS Code task
- Ensure antivirus or file locks arenāt blocking the venv
- City not found
- Check spelling or try a broader/canonical place name (e.g., āKingstonā vs āKingston, Jamaicaā)
- Alerts are empty
- No active warnings at this time or limited coverage by the warnings endpoint
- Networking issues
- Ensure your machine can reach the OpenāMeteo endpoints
Contributing
See CONTRIBUTING.md for guidelines on setting up your environment, running the demo, and opening PRs.
Security
Please see SECURITY.md for how to report vulnerabilities.
License
Licensed under the MIT License. See LICENSE for details.
Release notes
See CHANGELOG.md for version history.
What you get
- MCP server with tools, a resource, and a prompt:
get_weather(city, unit)
returns structured JSON (Pydantic) with temp, humidity, etc.get_alerts(city)
returns structured alerts list.- Resource:
weather://{city}
renders a short human string. - Prompt:
Weather Report
shows a reusable prompt template.
- MCP client that spawns the server via stdio and calls those APIs.
- VS Code tasks to install deps and run the demo.
- Optional Azure resource group provisioning commands (separate RG).
Requirements
- Python 3.10+
- pip (or uv if you prefer)
Setup
- Create a virtual environment and install deps
python -m venv .venv
. .venv/Scripts/Activate.ps1
pip install -r requirements.txt
- Run the client (it spawns the server process)
python client/client.py
Set a city:
$env:CITY = "Seattle"
python client/client.py
Expected output (abbrev.):
- Lists available tools
- Prints structured weather JSON and any alerts
- Reads the
weather://{city}
resource - Lists prompts
Project layout
server/server.py
ā FastMCP server exposing tools, resource, and a promptclient/client.py
ā MCP client that connects to the server over stdiorequirements.txt
ā Python deps (mcp SDK + pydantic).vscode/tasks.json
ā Run/install tasks.gitignore
ā Ignore venv, caches, etc.
VS Code tasks
Open the Command Palette ā "Run Task" and choose:
- Install dependencies
- Run Client (spawns server)
- Run Server (advanced/dev)
How it works
- The server uses the official MCP Python SDK (FastMCP) to declare tools/resources/prompts. MCP handles schema generation and structured outputs for you.
- The client launches the server as a child process and speaks MCP over stdio. It initializes a session, lists capabilities, calls tools, reads resources, and inspects prompts.
Optional: Azure resource group for related infra
This demo does not require Azure. If you want to keep any future cloud resources isolated, create and later delete a dedicated resource group. See the commands below in the Azure section generated by the assistant.
Publish to GitHub
- Initialize a git repo, commit, and push:
git init
git add .
git commit -m "MCP weather demo"
# Create a new repo on GitHub, then
git remote add origin https://github.com/<your-username>/mcp-weather-demo.git
git branch -M main
git push -u origin main
Troubleshooting
- Ensure your venv is activated when running commands.
- If you prefer uv:
uv venv
. .venv/Scripts/Activate.ps1
uv pip install -r requirements.txt
uv run python client/client.py