Authentication
All requests to the Xweather MCP Server must be authenticated with your combined Xweather API client id and secret (<client_id>_<client_secret>). Supply this token when connecting your agent or instantiating via code.
The domain for the service lives at
https://mcp.api.xweather.com/mcpMethods
| Method | When to use | Example |
|---|---|---|
| Authorization header | Agents and SDKs that let you configure custom headers. Provides the cleanest separation between auth and query parameters. | Authorization: Bearer <client_id>_<client_secret> |
| Query parameter | Default for agents that cannot use headers to connect (e.g., Claude, ChatGPT). | https://mcp.api.xweather.com/mcp?api_key=<client_id>_<client_secret> |
| OAuth 2.0 | Supported by most MCP clients, this will use an encoded JSON Web Token (JWT) in the Authorization header. | Authorization: Bearer <Base64 encoded JWT> |
For connection steps using these methods, see either the Agents or Code guide, depending on your use case.
OAuth 2.0
Many MCP clients support the use of OAuth 2.0. Connecting this way allows an encoded JSON Web Token (JWT) to be automatically sent in the Authorization header.
The process is similar for connecting using OAuth 2.0 via Claude, ChatGPT, or other MCP clients.
In the URL, simply provide https://mcp.api.xweather.com. Do not fill in anything for the OAuth Client ID and Secret fields. Those serve a different purpose than your Xweather credentials.
You will be redirected to the authorization server, which looks like the screenshot below. Enter your Xweather client ID and client secret here, and the app will handle the rest of the connection process.
From a user perspective, that's all you need to know to be on your way!
Error matrix
| Status | Scenario | Fix |
|---|---|---|
| 401 Unauthorized | Missing or malformed credential. The combined key is blank, truncated, or copied without the underscore. | Reissue the key from the Xweather dashboard and confirm the agent stores the full <client_id>_<client_secret> string. |
| 403 Forbidden | Key is valid but lacks the required subscription scope or the app is disabled. | Confirm the app is active and the subscription tier includes MCP access. Contact support if scopes need adjustment. |
| 429 Too Many Requests | Rate or concurrency limits exceeded for the credential. | Reduce parallel requests, add backoff, or upgrade the plan if workload requires higher throughput. |
Rotating credentials
- Regenerate keys from the Xweather dashboard and update any stored environment variables or secret stores.
- Refresh MCP connections in each agent. May require removing and adding the connector back again.