Ferramentas do MCP

Tipo

Referência

Para

Desenvolvedor, Analista

O MCP do Lumo expõe quatro ferramentas, todas de leitura: search_catalog, get_app, search_values e query. São as mesmas que o Chat com Dados e as skills usam, com os mesmos acessos do usuário conectado. Esta página descreve o que cada uma recebe e devolve.

Formato do resultado

Cada chamada devolve um texto, que é o que o modelo lê, e um resultado estruturado (structuredContent), que é o que uma integração deve usar. Quando a ferramenta falha, a resposta vem marcada como erro e o texto explica o motivo, muitas vezes com as alternativas parecidas.

As ferramentas são anotadas como somente leitura, idempotentes e sem efeito fora do Lumo.

Ferramenta	O que faz
search_catalog	Procura Indicadores, expressões e colunas nas Aplicações do usuário, ou lista o catálogo quando não recebe termos
get_app	Descreve uma Aplicação: tabelas, colunas, expressões, Indicadores e relacionamentos
search_values	Lista os valores de uma coluna, procura um texto nas colunas de texto ou mostra linhas de exemplo
query	Roda uma consulta agregada e devolve os números

search_catalog

Argumento	Descrição
terms	Uma lista de palavras, ou um texto só (tratado como um termo). O item volta quando casa com qualquer um dos termos, sem diferença de acento ou caixa. Sem termos, a ferramenta devolve o catálogo
appId	Limita a busca a uma Aplicação

Sem termos, o resultado traz legend e apps. Cada Aplicação vem com id, name, description, desk (a mesa; null em Minha Mesa), clonedFrom (a Aplicação de origem de uma cópia pessoal), publishedAt (null se nunca foi publicada), sameName (outras Aplicações com o mesmo nome) e indicators. O texto traz ainda uma amostra das colunas de cada Aplicação (as de data e as mais usadas em dashboards); o esquema completo vem do get_app. Um Indicador pode trazer alsoIn, as outras Aplicações com Indicador de mesmo nome. Use desk, clonedFrom e publishedAt para distinguir Aplicações homônimas.

Com termos, o resultado traz terms, total, shown e matches. Cada item tem kind (indicator, expression ou column), name e app. Um Indicador válido vem com example, a chamada de query pronta. Coluna e expressão vêm com ref e field, o objeto que entra em fields.

get_app

Argumento	Descrição
appId	A Aplicação a descrever

O resultado traz app, indicators, expressions, tables e relationships. Cada tabela diz se é fato ou dimensão e quando foi carregada, e lista columns com label, ref, field, type, role e unit.

search_values

Argumento	Descrição
appId	A Aplicação
ref	A coluna (ou, no modo sample, a tabela)
contains	Texto que estreita os valores. Todas as palavras precisam aparecer, sem diferença de acento ou caixa
mode	distinct (padrão) ou sample

Chamada	Resultado
Com ref	Até 50 valores distintos da coluna, em ordem, em values, e o total de distintos no texto. Só coluna de texto ou data: coluna numérica dá erro, e número se consulta com query. Em coluna de data, contains é ignorado
Sem ref, com contains	Procura o texto nas colunas de texto da Aplicação, as de dimensão primeiro: até 20 colunas, até 8 valores por coluna e 20 segundos no total. Traz mode: "search", matches (cada um com ref, values e more), columnsSearched e columnsTotal. O texto lista as colunas que ficaram de fora, para repetir a busca com ref
mode: "sample"	10 linhas de exemplo da tabela, sem colunas técnicas como ids, em columns e rows
Sem ref e sem contains	Erro

query

Argumentos

Argumento	Forma	Descrição
appId	número	A Aplicação consultada
fields	{ ref, agg?, bucket? }[]	As colunas do resultado. Sem agg, a coluna agrupa. Com agg, mede
filters	{ ref, op, value?, agg?, bucket? }[]	Os filtros. Com agg, corta pelo valor agregado. Com bucket, corta a data pelo recorte
orderBy	{ ref, dir, agg?, bucket? }[]	A ordenação, asc ou desc. A ref precisa estar em fields
limit	número	Linhas devolvidas. Sem limit, 10 (31 quando há data agrupada). O teto é 500 no MCP e 100 no chat

Sem orderBy, as linhas vêm numa ordem qualquer. Para um ranking, use orderBy com limit.

ref é Tabela.Coluna com o rótulo que a Aplicação mostra (Vendas.Valor líquido). Quando duas colunas da mesma tabela têm o mesmo rótulo, usa-se o nome físico (Vendas.VALOR_2). Uma expressão da Aplicação é o rótulo dela (Margem %) e entra só como { ref }. A ref ignora diferença de caixa e acento. Id de coluna, nome sem tabela e a sintaxe antiga são recusados, e o erro lista as refs parecidas.

agg aceita sum, avg, min, max, count e count_distinct. Os quatro primeiros valem para coluna numérica; as contagens, para qualquer coluna. Coluna numérica com papel de medida exige agg.

bucket vale só para coluna de data e aceita day, month, year, month_of_year, hour_of_day (de "00:00" a "23:00") e day_of_week (0 é domingo, 6 é sábado). Data sem bucket agrupa por dia. hour_of_day e day_of_week só fazem sentido em coluna com hora, e um filtro por eles lê a tabela inteira: combine com um intervalo de datas.

op aceita =, !=, >, <, >=, <=, between, not between, in, not in, like, not like, is null e is not null. in e between recebem lista (between é [início, fim], com datas em YYYY-MM-DD, ou YYYY-MM-DD HH:mm para um instante). is null e is not null não levam value. = "" traz as linhas em branco (nulo ou texto vazio) e != "" tira as duas. != com valor preenchido mantém as linhas em branco.

Antes de rodar, a ferramenta confere cada filtro de texto com = ou in contra os valores da coluna. Se o valor não existe, a consulta não roda e o erro traz os valores parecidos.

Colunas de tabelas diferentes combinam quando a Aplicação tem relacionamento entre elas.

{
  "appId": 7,
  "fields": [{ "ref": "Vendas.Valor da venda", "agg": "sum" }],
  "filters": [
    { "ref": "Vendas.Situação", "op": "=", "value": "Ativa" },
    { "ref": "Vendas.Data", "op": "between", "value": ["2026-09-01", "2026-09-30"] }
  ]
}

Resultado

Os números chegam crus, sem formatação de moeda ou percentual, e cada coluna diz a unidade.

Campo	Descrição
appId	A Aplicação consultada
columns	Uma por coluna: key, label, type e unit
rows	Uma lista por linha, na ordem de columns
rowCount	Linhas devolvidas
totalRows	Linhas que a consulta tem no total. A contagem para em 1 milhão
truncated	true quando vieram menos linhas que o total. As que faltam existem e não estão em rows
summary	O total sobre todas as linhas, inclusive as que não vieram, por key. Ausente quando a consulta não tem total
dataAsOf	A carga mais antiga entre as tabelas da consulta, em ISO 8601 no horário de Brasília. null quando alguma tabela nunca foi carregada
filtersApplied	Filtros e período aplicados, em palavras
permalink	Link para o mesmo resultado como relatório na Aplicação, quando há
empty	Presente quando não voltou linha (zero_rows) ou só zeros (all_zero)
notes	Ajuste que a consulta fez sozinha, quando houve

unit vale BRL, USD, GBP, percent, seconds, minutes ou bytes, e null para número simples ou texto. Percentual vem como fração (0.25 é 25%).

Quando a resposta é cortada, o texto diz "Linhas: N de M; as outras … existem e não estão aqui." Acima de 1 milhão, diz "de mais de 1.000.000". Sem linhas, diz "Nenhum registro para essa combinação de filtros."

Exemplo de resultado estruturado:

{
  "appId": 7,
  "columns": [
    { "key": "680301_AGP", "label": "Loja", "type": "string", "unit": null },
    { "key": "680302_SUM", "label": "Faturamento", "type": "number", "unit": "BRL" }
  ],
  "rows": [["Aurora", 4695447.08]],
  "rowCount": 1,
  "totalRows": 1,
  "truncated": false,
  "summary": { "680302_SUM": 4695447.08 },
  "dataAsOf": "2026-10-15T03:00:00-03:00",
  "filtersApplied": ["Ano = 2026"],
  "permalink": "https://<seu-dataviz>/app/7/report/..."
}

Recursos

Além das ferramentas, o servidor publica dois recursos em texto: lumo://apps, o catálogo do usuário, e lumo://app/{appId}, a descrição de cada Aplicação. São os mesmos textos de search_catalog sem termos e de get_app.

Limites

Limite	Valor
Linhas por consulta	500
Requisições por usuário	60 por minuto
Requisições por Tenant	300 por minuto

Acima do limite de requisições, o servidor responde 429 com o cabeçalho Retry-After.

Relacionado

• MCP do Lumo: conectar o Claude, o ChatGPT ou o Cursor
• API: integrações por REST, incluindo o streaming do chat