GribStream for AI tools

This page is the starting point for AI integrations with GribStream. It is intended for people and tools building workflows on top of GribStream with ChatGPT, Claude, Gemini, Codex, Claude Code, Cursor, custom agents, or any other AI runtime that can call tools and make HTTP requests.

The recommended integration for web chat tools is the hosted GribStream MCP connector. It helps AI tools discover datasets, resolve exact selectors, build valid /timeseries and /runs requests, validate expressions, and execute OAuth-protected live weather queries.

Hosted MCP connector

Use the hosted MCP connector when your AI tool supports remote MCP over Streamable HTTP.

https://gribstream.com/mcp

Use the URL exactly as shown. Do not include trailing punctuation such as a period when copying it into an MCP client.

The connector exposes read-only discovery, selector lookup, request building, and validation before OAuth. For live /timeseries and /runs query tools, GribStream OAuth asks you to sign in, approve the connector, and choose the active API token it should use. The raw API token is not shown to the AI client.

Before you connect

• Create or sign in to a GribStream account at /auth/login.
• Create an API token from /app/dashboard. A free API token is enough to authorize the MCP for supported free-tier usage.
• Enter https://gribstream.com/mcp exactly in the MCP URL field.
• Complete GribStream OAuth when your AI client asks. During OAuth, choose the API token the MCP should use for live data queries.
• If a manual OAuth form asks for a client secret, leave it empty. GribStream MCP uses a public OAuth client with PKCE, not a shared client secret.

If you connect the MCP before creating an API token, public discovery tools can still work, but authenticated data-query tools will not be able to run live weather queries until a token is available and selected.

Setup by client

AI vendor settings change frequently. The stable pieces are the remote MCP URL, Streamable HTTP transport, GribStream OAuth, and the requirement that your GribStream account has an API token before live data queries can run. The examples below follow the current public vendor documentation, but use the vendor documentation links when a product UI has moved.

codex mcp add gribstream --url https://gribstream.com/mcp
codex mcp list
codex mcp login gribstream

[mcp_servers.gribstream]
url = "https://gribstream.com/mcp"

claude mcp add --transport http gribstream https://gribstream.com/mcp
claude mcp list

gemini mcp add --transport http gribstream https://gribstream.com/mcp
gemini mcp list

{
  "mcpServers": {
    "gribstream": {
      "httpUrl": "https://gribstream.com/mcp",
      "timeout": 30000
    }
  }
}

What the MCP provides

GribStream MCP deliberately separates public planning tools from authenticated data-query tools.

• No auth / public / read-only: dataset metadata, parameter discovery, exact selector lookup, shared-parameter resolution, expression syntax guidance, request builders, and request validation.
• Auth required / data query: live /timeseries and /runs tools that fetch actual weather forecast values through the selected GribStream API token.
• Typed tabular output: CSV and NDJSON query results can be returned as inline MCP resources with row counts, byte counts, columns, previews, and suggested filenames.

If the user asks an AI tool to fetch, download, plot, analyze, or compare actual weather values, the tool should use the authenticated query tools. If only public read-only tools are visible, complete OAuth or switch to a direct API workflow with GRIBSTREAM_API_TOKEN.

Chat your way into an analysis

A forecast request can look reasonable and still be wrong. The connector helps the AI check the catalog, use exact selectors, choose the right endpoint, and validate the request before you run it.

A session can start broad:

What models does GribStream support for global forecasts?

Then narrow into a concrete request:

Build a request for temperature, wind speed, and relative humidity in Lisbon tomorrow.

Then keep iterating:

1. Make it a grid over Portugal at 0.5 degrees.
2. Show what this would have looked like using a model-run cutoff 18 hours ago.
3. Give me the last three model runs forecasting those same valid hours.
4. Switch from GFS to IFS and re-resolve the selectors.

With an authenticated hosted connector or a GribStream API token available to a local AI tool, that can turn into actual analysis: compare models, calculate mean absolute error against an analysis dataset, search for weather thresholds, or summarize where two models disagree most.

Data handling guidance

• Prefer CSV for tabular data, pandas workflows, plots, heatmaps, and comparisons.
• When an MCP result includes a typed CSV or NDJSON resource, parse the full resource content, not just the visible preview in the chat.
• When saving multiple MCP query results, use the returned suggested_filename so one model or dataset result does not overwrite another.
• Rows are not guaranteed to arrive sorted. Sort /timeseries output by location fields and forecasted_time; sort /runs output by location fields, forecasted_at, and forecasted_time.
• If a request is too large, split by time range first, variables second, and coordinates or grid space last.
• For direct API bulk downloads, use Accept: text/csv, Accept-Encoding: gzip, and curl --compressed.

Core resources

• Hosted MCP connector: https://gribstream.com/mcp - remote Streamable HTTP MCP endpoint for AI tools that support custom connectors.
• Vendor-neutral skill file - portable instructions for AI tools that need to use GribStream correctly.
• OpenAPI spec - machine-readable contract for catalog, /timeseries, and /runs.
• Swagger UI - browser view of the same OpenAPI contract.
• Quick-start - examples of direct data access, expressions, lead times, backtesting, and runs queries.
• Models and inventories - dataset-specific parameter reference and selector discovery.

Authentication setup

The hosted MCP connector uses OAuth for live MCP queries. During setup, sign in to GribStream with an account that already has an active API token, then approve the connector and choose which token it should use. A free API token is enough to complete the flow for supported free-tier usage. The raw token is not returned to the AI client.

1. Create or sign in to an account at /auth/login.
2. Create an API token from /app/dashboard.
3. Connect the MCP endpoint and complete the GribStream sign-in flow when your AI tool asks for authorization.

For local CLI tools, coding agents, or clients that do not support OAuth for remote MCP servers yet, load an API token into the environment from a private token file and use the generated API request or the portable skill file.

macOS or Linux shell setup. The editor command uses VISUAL or EDITOR if set and falls back to vi; opening the token file manually in your preferred editor is also fine.

mkdir -p ~/.config/gribstream
chmod 700 ~/.config/gribstream
touch ~/.config/gribstream/token
chmod 600 ~/.config/gribstream/token
"${VISUAL:-${EDITOR:-vi}}" ~/.config/gribstream/token
export GRIBSTREAM_API_TOKEN="$(tr -d '\r\n' < ~/.config/gribstream/token)"

Windows PowerShell setup. This opens Notepad for the token file; any editor that saves plain text is fine.

$dir = Join-Path $env:APPDATA "GribStream"
New-Item -ItemType Directory -Force $dir | Out-Null
$tokenFile = Join-Path $dir "token"
New-Item -ItemType File -Force $tokenFile | Out-Null
Start-Process notepad $tokenFile -Wait
$env:GRIBSTREAM_API_TOKEN = (Get-Content $tokenFile -Raw).Trim()

CLI tools typically inherit environment variables from the parent shell that launched them. In practice that means you should load GRIBSTREAM_API_TOKEN first and then start the tool from that same terminal session. If the tool is already running, restart it after setting the variable.

Paste the token into the editor, not into an export, set, or PowerShell assignment command, so it does not end up in shell history. Using an environment variable loaded from a private file, or a vendor secret store mapped to GRIBSTREAM_API_TOKEN, is preferred. Avoid pasting tokens into prompts, checked-in files, shell history, or reusable scripts.

What the skill teaches

The public skill file is intentionally strict about the things AI tools tend to get wrong:

• choosing /timeseries vs /runs
• treating all timestamps as UTC
• understanding that timesList means valid times on /timeseries and run times on /runs
• treating selectors as exact published tuples instead of free-form strings
• using catalog and shared-parameter endpoints when discovery or cross-dataset normalization is needed
• stopping and asking for clarification when natural-language requests are ambiguous

Recommended workflow for AI tools

1. Connect the hosted MCP at https://gribstream.com/mcp if your AI tool supports remote MCP.
2. Make sure the GribStream account used for OAuth has an active API token before asking for live values.
3. Ask the AI tool to use GribStream MCP to discover datasets, resolve selectors, and build a validated request. These read-only planning tools work before OAuth.
4. Review the generated request, especially time ranges, coordinates, grid size, variables, and expressions.
5. Use the authenticated MCP live query tools for web chat workflows, or run the generated request against the regular GribStream API with GRIBSTREAM_API_TOKEN for local file, script, and plotting workflows.
6. Use the OpenAPI spec, skill file, Quick-start, and Expressions pages as references or fallback inputs for tools that do not support MCP.

Raw file

The current public skill file can be fetched directly at:

https://gribstream.com/skills/gribstream-query.md

That file is meant to be portable across AI vendors. It is most useful for tools that do not support remote MCP yet.