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 is the hosted GribStream MCP connector. It helps AI tools discover datasets, resolve exact selectors, build valid /timeseries and /runs requests, validate expressions, and return copy-pasteable HTTP requests.

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.

Setup examples

ChatGPT

If your ChatGPT account or workspace supports custom MCP connectors, add a connector with:

• Name: GribStream
• Transport: Streamable HTTP
• URL: https://gribstream.com/mcp
• Authentication: OAuth / GribStream sign-in

Claude

In Claude, add a custom connector from the Connectors settings:

• Connector name: GribStream
• Connector URL: https://gribstream.com/mcp

Gemini CLI

Add this to ~/.gemini/settings.json:

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

Then start Gemini CLI and run /mcp to confirm the connector is available. If your CLI build does not complete OAuth for remote MCP servers, use the skill file or OpenAPI fallback with GRIBSTREAM_API_TOKEN.

What the MCP provides

• dataset discovery and metadata
• parameter and selector discovery with exact case-sensitive codes
• shared parameters for cross-dataset workflows such as wind speed or 2 m temperature
• expression syntax guidance, including supported func.* math helpers
• request builders for /timeseries and /runs
• request validation before you run a data query
• authenticated live query tools for /timeseries and /runs

Use the MCP to create and validate the request. These planning tools are available before authorization. When the connector is authenticated, it can also execute the request through the regular GribStream API.

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.

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. 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 or clients that do not support OAuth for remote MCP servers yet, set an API token as the environment variable GRIBSTREAM_API_TOKEN and use the generated API request or the portable skill file.

Recommended shell setup:

export GRIBSTREAM_API_TOKEN='YOUR_TOKEN_HERE'

CLI tools typically inherit environment variables from the parent shell that launched them. In practice that means you should export 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.

Using an environment variable or a vendor secret store mapped to that variable is preferred. Avoid pasting tokens into prompts, checked-in files, 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. 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.
3. Review the generated request, especially time ranges, coordinates, grid size, variables, and expressions.
4. Use the authenticated MCP live query tools, or run the generated request against the regular GribStream API with GRIBSTREAM_API_TOKEN.
5. 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.