Troubleshooting & Usage Guidelines

Troubleshooting

Use this checklist when something goes wrong while connecting to or using the Xweather MCP Server.

Symptom	Likely cause	Fix
`401 Unauthorized`	Missing/blank API key or copied without the underscore.	Reissue the key from the dashboard and reconnect the agent.
`403 Forbidden`	Account lacks MCP scope or app disabled.	Confirm subscription level, re-enable the app, or contact support.

Status	Description	Mitigation
`429 Too Many Requests`	Burst of concurrent tool calls exceeded plan allowance.	Add exponential backoff, queue requests, or request a higher tier.

“No tools available” error: Check for conflicting filters. Remove exclude_tags/include_tools that hide everything, or confirm the agent’s allowed_tools list is not empty.
Grey connector icon: The client cannot reach the MCP endpoint. Verify the URL, network VPN rules, and that your machine trusts Xweather certificates.

Tighten prompts to specify timeframe, units, or required outputs (table, chart description, warning level).
Log tool inputs/outputs and share examples with the docs team if the model misuses parameters.

To get the best experience with the MCP Server and help optimize your API call usage, here are a few helpful tips:

Use specific location names: Try to use canonical names for locations that might be ambiguous (e.g., "Springfield, IL" rather than just "Springfield"). This helps the model find the exact location you're looking for without incurring extra calls for reformatting the location. For best results, use place names consistent with our Weather API format. You can find examples in the supported place references (opens in a new tab).
Be specific about time period aggregations: When requesting aggregated data, keep in mind that each aggregation period and dimension generally requires a separate API call. For example, if you ask for both the highest and lowest temperatures for a city last month, that will incur a total of 2 calls. Similarly, requesting data for each month of the past year will also incur 2 calls as that is a single aggregation over a year.
Consider how locations are processed: When you're working with multiple locations or time periods, the system generally makes a call for each one. For example, requesting lightning reports across several cities will result in one call per city.