GribStream para ferramentas de IA

Esta página é o ponto de partida para integrar o GribStream com ChatGPT, Claude, Gemini, Codex, Claude Code, Cursor, agentes próprios ou qualquer ambiente de IA capaz de chamar ferramentas e fazer requisições HTTP.

A integração recomendada para ferramentas de chat web é o conector MCP hospedado do GribStream. Ele ajuda a descobrir datasets, resolver seletores exatos, construir requisições válidas para /timeseries e /runs, validar expressions e executar consultas meteorológicas em tempo real protegidas por OAuth.

Conector MCP hospedado

Use o conector MCP hospedado quando sua ferramenta de IA tiver suporte a MCP via Streamable HTTP.

https://gribstream.com/mcp

Use a URL exatamente como exibida. Não inclua pontuação final, como um ponto, ao copiá-la para um cliente MCP.

O conector permite descobrir datasets, resolver seletores, construir requisições e validar antes do OAuth. Para executar consultas em tempo real de /timeseries e /runs, o fluxo OAuth do GribStream pede que você faça login, aprove o conector e escolha o token de API ativo que ele deve usar. O token de API original não é mostrado ao cliente de IA.

Antes de conectar

• Crie uma conta ou faça login no GribStream em /auth/login.
• Crie um token de API em /app/dashboard. Um token de API gratuito basta para autorizar o MCP dentro do uso suportado pelo plano gratuito.
• Use a URL MCP exatamente como https://gribstream.com/mcp.
• Complete o OAuth do GribStream quando seu cliente de IA pedir. Durante o OAuth, escolha o token de API que o MCP deve usar para consultas de dados em tempo real.
• Se um formulário manual de OAuth pedir client secret, deixe em branco. O GribStream MCP usa um cliente OAuth público com PKCE, não um segredo compartilhado.

Se você conectar o MCP antes de criar um token de API, as ferramentas públicas de descoberta ainda podem funcionar, mas as ferramentas autenticadas de consulta de dados não conseguirão executar consultas meteorológicas em tempo real até que exista um token disponível e selecionado.

Configuração por cliente

As configurações dos provedores de IA mudam com frequência. As partes estáveis são a URL do MCP remoto, o transporte Streamable HTTP, o OAuth do GribStream e a exigência de que sua conta GribStream tenha um token de API antes de executar consultas de dados em tempo real. Os exemplos abaixo seguem a documentação pública atual dos fornecedores; use os links de referência se a interface do produto mudar.

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
    }
  }
}

O que o MCP fornece

O GribStream MCP separa deliberadamente ferramentas públicas de planejamento de ferramentas autenticadas de consulta de dados.

• No auth / public / read-only: metadados de datasets, descoberta de parâmetros, busca de seletores exatos, resolução de parâmetros compartilhados entre datasets, guia de sintaxe de expressions, ferramentas para montar requisições e validação de requisições.
• Auth required / data query: ferramentas em tempo real de /timeseries e /runs que buscam valores reais de previsão meteorológica pelo token de API selecionado do GribStream.
• Saída tabular tipada: resultados CSV e NDJSON podem ser retornados como recursos MCP incorporados com contagem de linhas, bytes, colunas, pré-visualizações e nomes de arquivo sugeridos.

Se o usuário pedir que uma ferramenta de IA obtenha, baixe, gere gráficos, analise ou compare valores meteorológicos reais, a ferramenta deve usar as ferramentas autenticadas de consulta. Se apenas ferramentas públicas somente leitura estiverem visíveis, complete OAuth ou use um fluxo de API direta com GRIBSTREAM_API_TOKEN.

Da conversa para a análise

Uma requisição de previsão pode parecer razoável e ainda assim estar errada. O conector ajuda a IA a conferir o catálogo, usar seletores exatos, escolher o endpoint certo e validar a requisição antes da execução.

Uma sessão pode começar com uma pergunta ampla:

Quais modelos o GribStream suporta para previsões globais?

Depois pode se afunilar para uma requisição concreta:

Construa uma requisição para temperatura, velocidade do vento e umidade relativa em Lisboa amanhã.

E continuar por iterações:

1. Transforme em uma grade sobre Portugal a 0,5 grau.
2. Mostre como isso teria ficado usando um corte por execução do modelo de 18 horas atrás.
3. Mostre as últimas três execuções do modelo para esses mesmos horários válidos.
4. Troque de GFS para IFS e resolva os seletores novamente.

Com um conector hospedado autenticado ou um token de API do GribStream disponível para uma ferramenta local de IA, isso pode virar análise real: comparar modelos, calcular erro absoluto médio contra um dataset de análise, procurar limiares meteorológicos ou resumir onde dois modelos divergem mais.

Orientação para lidar com dados

• Prefira CSV para dados tabulares, fluxos com pandas, gráficos, heatmaps e comparações.
• Quando um resultado MCP incluir um recurso CSV ou NDJSON tipado, analise o conteúdo completo do recurso, não apenas a pré-visualização visível no chat.
• Ao salvar vários resultados MCP, use o suggested_filename retornado para que um resultado de modelo ou dataset não sobrescreva outro.
• As linhas não têm ordem garantida. Ordene a saída de /timeseries por campos de localização e forecasted_time; ordene a saída de /runs por campos de localização, forecasted_at e forecasted_time.
• Se uma requisição for grande demais, divida primeiro por intervalo de tempo, depois por variáveis e por último por coordenadas ou espaço de grade.
• Para downloads grandes via API direta, use Accept: text/csv, Accept-Encoding: gzip e curl --compressed.

Recursos principais

• Conector MCP hospedado: https://gribstream.com/mcp - servidor MCP remoto Streamable HTTP para ferramentas de IA que suportam custom connectors.
• Arquivo de instruções independente de fornecedor - instruções portáteis para ferramentas de IA que precisam usar o GribStream corretamente.
• Especificação OpenAPI - contrato legível por máquina para catálogo, /timeseries e /runs.
• Swagger UI - visualização no navegador do mesmo contrato OpenAPI.
• Início rápido - exemplos de acesso direto a dados, expressions, lead times, backtesting e consultas de runs.
• Modelos e inventários - referência de parâmetros por dataset e descoberta de seletores.

Configuração de autenticação

O conector MCP hospedado usa OAuth para consultas MCP em tempo real. Durante a configuração, faça login no GribStream com uma conta que já tenha um token de API ativo, aprove o conector e escolha qual token ele deve usar. Um token de API gratuito basta para completar o fluxo dentro do uso suportado pelo plano gratuito. O token original não é devolvido ao cliente de IA.

1. Crie uma conta ou faça login em /auth/login.
2. Crie um token de API em /app/dashboard.
3. Conecte o endpoint MCP e complete o fluxo de login do GribStream quando sua ferramenta de IA pedir autorização.

Para ferramentas CLI locais, agentes de programação ou clientes que ainda não suportam OAuth para servidores MCP remotos, carregue um token de API no ambiente a partir de um arquivo privado com o token e use a requisição gerada ou o arquivo de instruções portátil.

Configuração de shell para macOS ou Linux. O comando do editor usa VISUAL ou EDITOR se estiver definido e cai para vi; abrir o arquivo de token manualmente no seu editor preferido também funciona.

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)"

Configuração no Windows PowerShell. Isto abre o Notepad para o arquivo de token; qualquer editor que salve texto simples serve.

$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()

Ferramentas CLI normalmente herdam variáveis de ambiente do shell pai que as iniciou. Na prática, carregue GRIBSTREAM_API_TOKEN primeiro e depois inicie a ferramenta a partir da mesma sessão de terminal. Se a ferramenta já estiver rodando, reinicie depois de definir a variável.

Cole o token no editor, não em um comando export, set ou atribuição PowerShell, para que ele não acabe no histórico do shell. É preferível usar uma variável de ambiente carregada de um arquivo privado, ou um cofre de segredos do fornecedor mapeado para GRIBSTREAM_API_TOKEN. Evite colar tokens em prompts, arquivos versionados, histórico do shell ou scripts reutilizáveis.

O que o arquivo de instruções ensina

O arquivo público de instruções é propositalmente rigoroso sobre os erros que ferramentas de IA costumam cometer:

• escolher entre /timeseries e /runs
• tratar todas as marcas temporais como UTC
• entender que timesList significa horários válidos em /timeseries e horários de execução do modelo em /runs
• tratar seletores como tuplas publicadas exatas, não como texto livre
• usar endpoints de catálogo e de parâmetros compartilhados quando for preciso descobrir seletores ou normalizar entre datasets
• parar e pedir esclarecimento quando pedidos em linguagem natural são ambíguos

Fluxo recomendado para ferramentas de IA

1. Conecte o MCP hospedado em https://gribstream.com/mcp se sua ferramenta tiver suporte a MCP remoto.
2. Garanta que a conta GribStream usada no OAuth tenha um token de API ativo antes de pedir valores em tempo real.
3. Peça à ferramenta para usar o GribStream MCP para descobrir datasets, resolver seletores e construir uma requisição validada. Essas ferramentas de planejamento somente leitura funcionam antes do OAuth.
4. Revise a requisição gerada, especialmente intervalos de tempo, coordenadas, tamanho da grade, variáveis e expressions.
5. Use as ferramentas MCP autenticadas de consulta em tempo real em chats web, ou execute a requisição gerada contra a API normal do GribStream com GRIBSTREAM_API_TOKEN para fluxos locais com arquivos, scripts e gráficos.
6. Use a especificação OpenAPI, o arquivo de instruções, o início rápido e a página de Expressions como referências ou alternativa para ferramentas que não suportam MCP.

Arquivo bruto

O arquivo público de instruções atual pode ser baixado diretamente em:

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

Esse arquivo foi pensado para ser portátil entre fornecedores de IA. Ele é mais útil para ferramentas que ainda não suportam MCP remoto.