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.
| Name | Required | Description | Default |
|---|---|---|---|
| cities | Yes | List of cities to compare (1-10) | |
| units | No | Unit system: metric (°C, km/h) or imperial (°F, mph) | metric |
| Name | Required | Description |
|---|---|---|
| units | Yes | |
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint and openWorldHint. The description adds streaming progress and cancellation, which are behavioral traits beyond the annotations. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no waste. Front-loaded with purpose, then behavioral details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. The description covers purpose, streaming, and cancellation. Complete for a comparison tool with clear annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline 3. The description adds no additional meaning to the parameters; it does not explain 'cities' or 'units' beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Compare current weather across several cities.' The verb 'compare' and resource 'weather across several cities' are specific. It distinguishes from the sibling tool 'get_weather' which presumably handles single cities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs. alternatives. The sibling tool 'get_weather' implies single-city use, but the description does not state that directly or provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City name, e.g. 'London' or 'San Francisco' | |
| units | No | Unit system: metric (°C, km/h) or imperial (°F, mph) | metric |
| includeAdvice | No | If true, ask the host LLM (via MCP sampling) for a short what-to-wear tip |
| Name | Required | Description |
|---|---|---|
| city | Yes | |
| country | Yes | |
| latitude | Yes | |
| longitude | Yes | |
| observedAt | Yes | ISO timestamp of the observation |
| units | Yes | |
| temperature | Yes | |
| apparentTemperature | Yes | |
| humidity | Yes | Relative humidity (%) |
| windSpeed | Yes | |
| weatherCode | Yes | WMO weather interpretation code |
| conditions | Yes | Human-readable condition |
| temperatureUnit | Yes | |
| windSpeedUnit | Yes | |
| advice | No | LLM-generated recommendation (present only if sampling ran) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses that it can ask for clarification on ambiguous names and optionally include a what-to-wear tip via MCP sampling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences cover all essential information without redundancy, making it highly concise and efficiently front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists, the description adequately covers key behaviors (weather retrieval, ambiguity handling, optional advice) and complements the sibling tool differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3; the description adds meaning by linking the 'city' parameter to disambiguation behavior and the 'includeAdvice' parameter to the optional tip.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves current weather for a city, distinguishes itself from sibling 'compare_weather' by focusing on single-city current conditions, and explicitly mentions behavior for ambiguous city names.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on when the tool might ask for disambiguation (ambiguous city names), but does not specify when not to use it or alternatives like 'compare_weather'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.0.0compare_weatherget_weatherScored 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