Visual Crossing Weather MCP Server Guide

June 17, 2026

Visual Crossing MCP Server Beta

The Visual Crossing Weather MCP Server connects AI agents and MCP-compatible clients to global weather forecasts, historical weather data, and weather analytics through the Visual Crossing Weather API. It is designed for teams building AI assistants, agent workflows, weather-aware applications, and automated decision systems that need reliable weather data through Model Context Protocol.

The Visual Crossing Weather MCP Server lets approved beta testers connect MCP-compatible AI clients such as Claude Desktop and MCP Inspector to Visual Crossing weather data through a standard Model Context Protocol interface.

This release is currently in beta and available by invitation only. Access is limited to approved testers and partner accounts. If you would like to participate, contact Visual Crossing support.

What Is MCP?

MCP, or Model Context Protocol, is an open standard that allows AI applications to connect to external systems such as APIs, databases, tools, and workflows. For Visual Crossing, MCP provides a standard way for AI clients to discover and call weather tools backed by the Visual Crossing Weather API.

In practical terms, MCP lets a client such as Claude Desktop, MCP Inspector, or another MCP-compatible application discover available tools, understand how to call them, and retrieve structured results in a standard format.

For Visual Crossing, this means testers can connect AI-enabled tools directly to the Visual Crossing MCP server, which exposes weather capabilities through a consistent MCP interface. Instead of building and maintaining a separate custom integration for each client, testers can use one standard MCP connection model across compatible tools and focus on validating weather use cases, outputs, and account entitlements.

Why MCP Matters

MCP makes it easier to turn weather data into something an AI client can actually use.

Benefits include:

a standard connection model across multiple clients
simpler testing and onboarding for partners
structured weather responses that are easier for tools and agents to interpret
a cleaner path for expanding from one weather tool today to additional capabilities over time

Weather MCP Server Use Cases

The Visual Crossing MCP beta is designed for AI assistants, agents, and developer tools that need direct access to weather data without building a custom Weather API integration.

Example use cases include:

asking an AI assistant for forecast or historical weather data for a location
validating weather-sensitive workflows inside an AI agent
testing weather retrieval from Claude Desktop, MCP Inspector, or another MCP-compatible client
prototyping agent workflows that use weather forecasts, historical weather, solar radiation, agriculture, or air quality data
evaluating how Visual Crossing account entitlements map to MCP tool access

What You Can Do in This Beta

The current beta exposes one weather retrieval tool:

- `get_weather`

`get_weather` Tool Parameters

Parameter	Required	Description	Example
`latitude`	Yes	Decimal latitude for the weather location.	`40.7128`
`longitude`	Yes	Decimal longitude for the weather location.	`-74.0060`
`startDate`	Yes	First date to retrieve, in `YYYY-MM-DD` format.	`2026-06-17`
`endDate`	Optional	Last date to retrieve, in `YYYY-MM-DD` format. If omitted, the tool may return a single date or default range depending on account settings.	`2026-06-19`
`units`	Optional	Unit system for returned values. Common values include `us`, `metric`, and `uk`.	`us`
`include`	Optional	Weather sections to include, subject to beta entitlement.	`["days"]`
`elements`	Optional	Specific weather fields to return.	`["datetime", "temp", "tempmin", "tempmax"]`

This tool supports timeline-style weather retrieval for approved Visual Crossing accounts. Depending on your account and beta entitlement, limits may apply to date range, include values, and supported elements. Supported parameters and limits may vary during beta based on your account entitlement and the MCP client being tested.If you are new to Visual Crossing weather parameters, use the Query Builder or Weather Data Dictionary to explore available elements before calling get_weather through MCP.

MCP Server URL

Use this MCP server URL:

https://mcp.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/mcp

Quick Start

Choose the authentication path that matches your testing setup.

Option 1. API Key

Best for existing Visual Crossing Weather API customers, automated tests, and quick MCP interoperability checks.

You provide:

a beta-enabled Visual Crossing user account
a Visual Crossing API key

Option 2. User OAuth

Best for interactive desktop clients such as Claude Desktop or MCP Inspector.

In the current invite-only beta, Visual Crossing enables user OAuth access as part of onboarding.

Visual Crossing provides:

OAuth client configuration for approved tester flows
beta enablement for your account
support for callback and scope setup when needed for supported clients

You provide:

a beta-enabled Visual Crossing user account
the client and callback details required by your testing tool (for example Claude Desktop or MCP Inspector)

Option 3. Machine-to-Machine (M2M) OAuth

Best for server-to-server integrations and backend services.

In the current invite-only beta, Visual Crossing provisions this setup for approved testers.

Visual Crossing provides:

a Cognito app client for your integration
a client secret for that app client
a Visual Crossing-approved mapping from that app client to your account

You provide:

your integration endpoint or service details for onboarding
secure storage and handling of the issued client secret

Authentication Methods

1. API Key Authentication

Use this when Visual Crossing has provisioned an API key for your account.

How it works:

You send X-VC-API-Key with MCP requests.
No OAuth token exchange is required.

Best for:

Existing Visual Crossing API customers
Simple scripted testing
Direct validation in MCP Inspector

We recommend creating a dedicated API key for MCP usage so that MCP traffic can be monitored, rotated, or disabled independently from your other Weather API integrations. You can do this on your account page. For more information, see Managing Team Users and API keys.

2. User OAuth Authentication

Use this when a human tester is signing in through an OAuth-enabled MCP client such as Claude Desktop or MCP Inspector.

How it works:

Your client redirects you to a Cognito-hosted login flow.
After sign-in, the client receives a bearer token and uses it for MCP calls.

Best for:

Interactive desktop clients
End-user testing
Validating OAuth discovery and browser sign-in behavior

3. Machine-to-Machine (M2M) OAuth Authentication

Use this when a backend service, partner integration, or scheduled job is calling MCP without a human sign-in.

How it works:

A Cognito app client uses client_credentials to obtain a bearer token.
That app client must be mapped by Visual Crossing to the correct account before MCP access will succeed.

Best for:

Server-to-server integrations
Automated workflows
Partner service integrations

Typical MCP Session Flow

Most testers will follow this sequence:

Connect to the MCP endpoint
Authenticate using one of the supported methods
Create or resume an MCP session if required by your client or transport
Run initialize
Run tools/list
Confirm get_weather is available
Run tools/call for get_weather

Example `get_weather` Request

Example tool call payload:

{
  "name": "get_weather",
  "arguments": {
    "latitude": 40.7128,
    "longitude": -74.0060,
    "startDate": "2026-06-17",
    "endDate": "2026-06-19",
    "units": "us",
    "include": ["days"],
    "elements": ["datetime", "temp", "tempmin", "tempmax"]
  }
}

Expected result:

The tool returns structured weather data for the requested location, date range, unit group, and selected elements.

Testing With Claude Desktop

Claude Desktop is a good way to validate the user-authenticated OAuth flow.

Recommended approach:

Add the Visual Crossing MCP server in Claude Desktop using the MCP server URL.
Start the connection flow.
When prompted, sign in through the Cognito-hosted browser flow.
After authorization completes, return to Claude Desktop.
Ask Claude to list available tools or request weather for a location and date range.

What this validates:

OAuth discovery
browser-based login flow
user token exchange
MCP tool availability
get_weather execution

If you receive an OAuth callback or redirect mismatch error, contact support and include the exact callback URL shown by the client.

Example Prompts for MCP Clients

After connecting the Visual Crossing MCP server, try prompts such as:

“List the available Visual Crossing MCP tools.”
“Get the daily forecast for New York City from June 17 to June 19.”
“Retrieve temperature, precipitation, and wind speed for this latitude and longitude.”
“Compare today’s forecast with the historical weather for the same location.”
“Use Visual Crossing weather data to check whether outdoor work conditions may be affected by heat, wind, or rain.”

Testing With MCP Inspector

MCP Inspector is a good general-purpose client for beta testing.

Launch Inspector:

npx -y @modelcontextprotocol/inspector

Then open the localhost URL shown by Inspector in your browser.

Inspector With API Key

Configure Inspector to connect to:

https://mcp.visualcrossing.com/VisualCrossingWebServices/rest/api/v1/mcp

Add header:

X-VC-API-Key: YOUR_API_KEY

Then run:

initialize
tools/list
tools/call

Inspector With User OAuth

Inspector can also test the user-authenticated OAuth flow.

Requirements:

Your Visual Crossing beta account must be enabled for OAuth access.
The OAuth client must have the correct callback URL configured.

In this mode, Inspector drives the browser login flow and then continues using the returned bearer token.

Inspector With Machine-to-Machine (M2M) OAuth

Inspector is useful for Machine-to-Machine (M2M) testing if you already have a bearer token.

Recommended pattern:

Mint a token externally using client_credentials
Add header in Inspector:

Authorization: Bearer YOUR_ACCESS_TOKEN

Run the same MCP flow:

initialize
tools/list
tools/call

Machine-to-Machine (M2M) Token Example

A service can obtain an OAuth token from Cognito using the token endpoint and the client_credentials grant.

Example PowerShell:

$clientId = "YOUR_CLIENT_ID"
$clientSecret = "YOUR_CLIENT_SECRET"
$scope = "visualcrossing-api/mcp.tools.invoke visualcrossing-api/mcp.tools.read"
$tokenUrl = "YOUR_VISUAL_CROSSING_TOKEN_URL"
$basic = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${clientId}:${clientSecret}"))
$response = Invoke-RestMethod -Method Post -Uri $tokenUrl -Headers @{ Authorization = "Basic $basic" } -ContentType "application/x-www-form-urlencoded" -Body ("grant_type=client_credentials&scope=" + [uri]::EscapeDataString($scope))
$response.access_token

Important:

The Cognito app client must be provisioned before use.
Visual Crossing provides the token endpoint, client ID, client secret, and required scopes during M2M onboarding.
The app client must be mapped by Visual Crossing to the target account before MCP access will succeed.

Current Beta Limitations

During the beta, access may be restricted by client, account, or support-approved configuration. Examples include:

allowed include values
maximum date range
allowed elements
forecast versus history access
hourly versus daily access

Testers should not assume that all accounts receive identical capability limits.

Security Guidance

Do not share API keys, client secrets, or bearer tokens in email or chat.
Rotate any test credentials that may have been exposed during troubleshooting.
Treat MCP access as account-scoped access to your Visual Crossing data entitlements.

Troubleshooting

API Key Authentication Fails

Confirm the key is active.
Confirm the key belongs to the intended Visual Crossing account.
Confirm the account is enabled for MCP beta access.

OAuth Browser Flow Fails

Confirm the OAuth client callback URL is configured correctly.
Confirm the account is enabled for beta access.
Confirm the requested scopes are allowed.

M2M OAuth Fails After Token Issuance

Confirm the Cognito app client is mapped by Visual Crossing to the correct account.
Confirm the target account is enabled for MCP beta access.
Confirm the token includes the required MCP scopes.

Tool Is Visible But Request Is Rejected

Your account or client may be subject to beta limits on parameters such as date range, include values, or supported elements.
Contact support with the request details and the approximate time of the failure.

Frequently Asked Questions

Is the Visual Crossing MCP server available publicly?

The Visual Crossing MCP server is currently in invite-only beta. Access is limited to approved testers and partner accounts.

What weather data can I access through MCP?

The current beta exposes weather retrieval through the get_weather tool. Available date ranges, include options, and weather elements depend on your Visual Crossing account entitlement and beta configuration.

Can I use the Visual Crossing MCP server with Claude Desktop?

Yes, approved beta testers can use compatible MCP clients such as Claude Desktop when the required authentication flow has been enabled for their account.

Can I use an API key instead of OAuth?

Yes. API key authentication is available for approved beta accounts by sending the X-VC-API-Key header with MCP requests.

Does MCP replace the Visual Crossing Weather API?

No. MCP provides a standard AI-client interface to Visual Crossing weather capabilities. Developers can continue using the Visual Crossing Weather API directly for application integrations, dashboards, and backend services.

Support

Visual Crossing MCP is currently beta and invite only.

For access requests, provisioning questions, entitlement issues, or beta support, contact Visual Crossing support.

Visual Crossing Weather MCP Server Guide

Visual Crossing MCP Server Beta

What Is MCP?

Why MCP Matters

Weather MCP Server Use Cases

What You Can Do in This Beta

get_weather Tool Parameters

MCP Server URL

Quick Start

Option 1. API Key

Option 2. User OAuth

Option 3. Machine-to-Machine (M2M) OAuth

Authentication Methods

1. API Key Authentication

2. User OAuth Authentication

3. Machine-to-Machine (M2M) OAuth Authentication

Typical MCP Session Flow

Example get_weather Request

Testing With Claude Desktop

Example Prompts for MCP Clients

Testing With MCP Inspector

Inspector With API Key

Inspector With User OAuth

Inspector With Machine-to-Machine (M2M) OAuth

Machine-to-Machine (M2M) Token Example

Current Beta Limitations

Security Guidance

Troubleshooting

API Key Authentication Fails

OAuth Browser Flow Fails

M2M OAuth Fails After Token Issuance

Tool Is Visible But Request Is Rejected

Frequently Asked Questions

Is the Visual Crossing MCP server available publicly?

What weather data can I access through MCP?

Can I use the Visual Crossing MCP server with Claude Desktop?

Can I use an API key instead of OAuth?

Does MCP replace the Visual Crossing Weather API?

Support

`get_weather` Tool Parameters

Example `get_weather` Request