Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Weather Pro what's the weather in New York?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server that exposes real-time weather, built to demonstrate the full MCP surface — not just tools — and to run like a real service (dual transport, auth, caching, retries, tests, Docker, CI).
It is the "after" to a deliberately minimal "before"
(../mcp-real-weather-api), which exposes a single
get_weather tool over stdio and nothing else.
Targets the current stable spec, MCP 2025-11-25, via
@modelcontextprotocol/sdk.
MCP concept | Where to see it | What it proves |
Structured output |
| Tool results are typed & machine-readable, not opaque text |
Tool annotations |
| Server signals to the host that a tool is safe to auto-run |
Input validation | Zod | Bad arguments are rejected before our code runs |
Elicitation |
| Server pauses to ask the user a structured question |
Sampling |
| Server asks the client's LLM for advice — ships no LLM SDK itself |
Progress |
| Long-running tool streams incremental progress + supports cancel |
Resources (direct) |
| Fixed, read-only context (WMO code table) |
Resource templates |
| Parameterised, discoverable data (RFC 6570 URIs) |
Completions |
| Suggests valid argument values as you type |
Prompts |
| Reusable, user-invoked workflow (slash command) |
Logging |
| Structured observability over the protocol |
See DEMO.md for the guided walkthrough / talking points.
Related MCP server: mcp-weather
npm install
npm test # unit tests (offline, deterministic)
npm run inspect # open the MCP Inspector against the stdio server# Local (stdio) — for Claude Desktop, IDEs
npm start
# Remote (HTTP) — for multi-client / deployment
MCP_TRANSPORT=http PORT=3000 MCP_AUTH_TOKEN=changeme npm run start:httpEnd-to-end smoke tests (hit the live Open-Meteo API):
npm run smoke # spawns + drives the stdio server
# In one terminal: MCP_TRANSPORT=http PORT=3030 MCP_AUTH_TOKEN=demo-secret npm start
npm run smoke:http # drives the running HTTP serverAdd to your MCP client config (e.g. claude_desktop_config.json):
{
"mcpServers": {
"weather-pro": {
"command": "node",
"args": ["/absolute/path/to/mcp-weather-pro/src/index.js"]
}
}
}{
"mcpServers": {
"weather-pro": {
"type": "http",
"url": "http://localhost:3000/mcp",
"headers": { "Authorization": "Bearer changeme" }
}
}
}src/
index.js entrypoint — selects transport from MCP_TRANSPORT
config.js env-driven config (one source of truth)
logger.js structured JSON logs → stderr (stdout is the protocol!)
cache.js bounded TTL cache (hit/miss stats)
httpClient.js axios + timeout + retry/backoff for upstream calls
schemas.js Zod input/output schemas (validation + structured output)
server.js builds the McpServer and registers every primitive
services/
geo.js geocoding + ambiguity detection (powers elicitation)
weather.js current + forecast + WMO code mapping + units
cities.js static list for completions
features/
tools.js get_weather, compare_weather
resources.js direct resource + two templates
prompts.js plan-my-day
transports/
stdio.js local transport + graceful shutdown
http.js Streamable HTTP + Bearer auth + sessions + /healthDual transport (stdio + Streamable HTTP) from one codebase.
Auth — Bearer token on every HTTP /mcp call; /health left open.
Resilience — per-call timeouts, bounded exponential backoff with jitter.
Caching — geocoding (24h) and weather (5m) with bounded size + eviction.
Validation — Zod on all tool inputs; SDK validates structured output.
Graceful degradation — elicitation/sampling are used only if the client supports them; otherwise the tool still returns a correct result.
Observability — structured stderr logs + protocol-level logging.
Tests & CI — unit tests on Node 18/20/22 + a Docker build in GitHub Actions.
Containerised — multi-stage-friendly Dockerfile with a healthcheck.
MIT
Compare current weather across several cities. Streams progress as each city is fetched, and can be cancelled mid-flight.
Inputs: cities (required), units. Returns: units, results
Get current weather for a city. If the city name is ambiguous, asks you which one you meant. Optionally returns a what-to-wear tip.
Inputs: city (required), units, includeAdvice. Returns: city, country, latitude, longitude, +11 more
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 2 tools
The two tools, get_weather and compare_weather, have clearly distinct purposes. get_weather focuses on a single city, while compare_weather handles multiple cities, so there is no ambiguity.
Both tools follow a consistent verb_noun pattern (compare_weather and get_weather) using snake_case. The naming is predictable and easy to parse.
With only 2 tools, the server is on the low end for a weather service, especially given the 'Pro' name. While the tools are useful, the count feels thin for comprehensive weather coverage.
The server covers current weather and comparison but lacks common operations like forecast or historical data. This is a notable gap for a weather-focused server.
Hosted MCP server for Xweather weather data: conditions, forecasts, alerts, and more.
MCP server for weather with reasoning — umbrella advice, outdoor checks, city comparisons.
Hosted MCP server for live public-data APIs and Skills for AI agents.
An MCP server for weather information by @kulybaba