Grist

Transforme as planilhas que gerenciam seu negócio em aplicativos seguros.

Ver em getgrist.comExperimente este MCPPatrocinado

Documentação

Servidor MCP do Grist

O Model Context Protocol (MCP) é um padrão aberto que permite que assistentes de IA acessem dados externos. Qualquer ferramenta compatível com MCP (como Claude ou ChatGPT) pode usar o servidor MCP do Grist para trabalhar com seus sites de equipe e documentos: listar e pesquisar tabelas, ler e consultar linhas, adicionar ou atualizar linhas, e criar novos documentos e tabelas.

[!note] Quer adicionar um conector do Grist? Conecte o Grist ao Claude

Para ChatGPT, veja as instruções abaixo.

Para o assistente de IA integrado do Grist, veja Assistente de IA.

Configurando o servidor MCP

O servidor MCP do Grist está disponível no Grist Hospedado e na edição completa do Grist auto-hospedado.

Grist Hospedado

No Grist Hospedado (getgrist.com), o servidor MCP já está ativado, sem necessidade de configuração. Ele está disponível para todas as contas do Grist em todos os planos, embora isso possa mudar no futuro.

Grist auto-hospedado

Na edição completa do Grist auto-hospedado, o servidor MCP está desativado por padrão. Ative-o definindo esta variável de ambiente na sua instância:

GRIST_MCP_ENABLED=true

[!note] Quer experimentar a edição completa? Você pode experimentar a edição completa do Grist gratuitamente por 30 dias. Saiba como ativá-la.

Indivíduos e pequenas empresas podem se qualificar para uma chave de ativação gratuita da edição completa. Consulte as perguntas frequentes sobre chaves de ativação.

Isso é suficiente para clientes que autenticam com uma chave de API do Grist: o usuário fornece sua chave em um cabeçalho Authorization e se conecta, sem necessidade de mais configuração do seu lado. Assistentes de IA como Claude.ai, Claude Desktop e ChatGPT fazem login interativamente e precisam de algumas configurações adicionais.

Login interativo (Claude, ChatGPT e similares)

Assistentes como Claude e ChatGPT fazem seu login pelo Grist em vez de usar uma chave de API. Eles autenticam pelo servidor OIDC integrado do Grist, que você ativa com:

GRIST_ENABLE_OIDC_SERVER=true

Esses assistentes se registram automaticamente usando CIMD (Client ID Metadata Documents). Permita-os listando os hosts dos quais você confia que eles venham:

GRIST_OIDC_CIMD_ALLOWED_HOSTS=claude.ai,chatgpt.com

Depois de definir ambas as variáveis, os usuários podem conectar qualquer assistente da sua lista.

[!note] Clientes que não suportam CIMD Alguns assistentes não conseguem se registrar via CIMD. Para esses, configure um aplicativo OAuth no Grist e use-o com um cliente de sua escolha.

Conectando seu cliente MCP

Aponte seu cliente para a URL do servidor MCP do Grist:

Grist Hospedado: https://docs.getgrist.com/api/mcp, uma URL para cada site de equipe e seu site pessoal.
Grist auto-hospedado: https://<your-grist-host>/api/mcp, seu próprio host; cobre todos os sites de equipe e pessoais nessa instância.

Os clientes podem autenticar de várias formas: chaves de API, contas de serviço, aplicativos OAuth registrados e CIMD (Client ID Metadata Documents), o padrão preferido que permite que um cliente se registre automaticamente a partir de uma URL de metadados em vez de ser configurado antecipadamente.

Exemplos de conexão

Estes exemplos mostram Claude e ChatGPT. Outros clientes seguem o mesmo fluxo de conector personalizado.

Claude.ai ou Claude Desktop

[!warning] Listagem de diretório em revisão A listagem do Grist no diretório do Claude ainda está em revisão pela Anthropic e não está ativa. Até que seja publicada, use o link especial 'Conecte o Grist ao Claude'.

O link 'Conecte o Grist ao Claude' abre a caixa de diálogo 'Adicionar conector personalizado' do Claude com o nome do Grist e a URL do MCP pré-preenchidos, então você só precisa confirmar a caixa de diálogo e fazer login:

Conecte o Grist ao Claude

Depois de clicar no link:

Na caixa de diálogo 'Adicionar conector personalizado', clique em 'Adicionar'.
Faça login com suas credenciais habituais do Grist (Google ou e-mail).
Revise as permissões e clique em 'Permitir' na tela de consentimento.

add-connector

ChatGPT

[!note] Modo de desenvolvedor necessário Adicionar um servidor MCP personalizado no ChatGPT requer o modo de desenvolvedor. Ative-o em Configurações > Aplicativos > Configurações avançadas.

No ChatGPT, abra Configurações > Aplicativos. Em Configurações avançadas, clique em Criar aplicativo. chatgpt-apps
Preencha o formulário Novo aplicativo:
- Nome: Grist. O ícone e a descrição são opcionais.
  - Conexão: mantenha URL do servidor selecionado e insira https://docs.getgrist.com/api/mcp, ou https://<your-grist-host>/api/mcp para Grist auto-hospedado.
  - Autenticação: escolha OAuth.
  - Marque Entendo e quero continuar para aceitar o aviso de servidor personalizado. chatgpt-new-app
Clique em Criar. O ChatGPT abre uma janela do navegador para você fazer login no Grist e aprovar as permissões na tela de consentimento.

Aplicativos de terminal (Claude Code, Gemini CLI e similares)

A maioria dos assistentes baseados em terminal adiciona um servidor MCP com um único comando. Para Claude Code:

claude mcp add --transport http grist https://docs.getgrist.com/api/mcp

Outras ferramentas, como Gemini CLI, usam um comando semelhante. Consulte a documentação da sua ferramenta para a sintaxe exata. No primeiro uso, a ferramenta abre um navegador para você fazer login no Grist e aprovar as permissões necessárias.

Visão geral das permissões solicitadas pelo Grist

Antes de usar o conector, seu cliente envia você ao Grist para fazer login. O Grist mostra qual aplicativo está solicitando acesso (Claude neste exemplo, com nome e URL) e permite escolher a conta para continuar ou adicionar outra conta.

grist-account-picker

A tela de consentimento do Grist então solicita ao seu cliente MCP um conjunto de escopos de acesso. Cada escopo tem um rótulo, e o nome subjacente do escopo é mostrado entre parênteses.

Identificar você (openid, email, profile): confirmar quem você é e passar seu nome e e-mail ao cliente para que ele possa mostrar sua conta.
Ler seu perfil (user.profile:read): permitir que a ferramenta get_user_profile consulte seu nome e e-mail, para que o cliente possa confirmar com qual conta do Grist está conectado.
Manter conectado (offline_access): manter a conexão funcionando sem pedir que você faça login novamente, inclusive quando o cliente age em seu nome enquanto você está ausente, como durante uma execução agendada.
Ler documentos (doc:read): listar e consultar tabelas, registros, colunas e anexos.
Modificar registros (doc:write): adicionar, atualizar e remover linhas.
Modificar esquema (doc.schema:write): adicionar, renomear ou remover tabelas e colunas.
Baixar documentos (doc:download): baixar documentos completos. Não usado por nenhuma ferramenta MCP atualmente.
Gerenciar webhooks (doc:webhooks): criar, ler, atualizar e excluir webhooks de documentos.

Um cliente não precisa solicitar todas as permissões antecipadamente. Ele pode solicitar apenas o que precisa inicialmente, como acesso somente leitura, e você aprova isso na tela de consentimento. Se uma ferramenta precisar de mais depois, alguns clientes pedem que você aprove a permissão extra naquele momento e continuam após a aprovação. Se o seu não fizer isso, reconecte o Grist nas configurações do conector do seu cliente e aprove o acesso mais amplo.

Escolhendo quais recursos seu cliente MCP pode acessar

grist-consent

A mesma tela de consentimento também pergunta quais recursos do Grist o cliente pode acessar. Você tem duas opções:

Todos os documentos (agora e no futuro). O cliente pode ver e agir em todos os sites de equipe, espaços de trabalho e documentos aos quais sua conta tem acesso, incluindo os que você criar depois. Este é o padrão.
Recursos selecionados. Escolha sites de equipe, espaços de trabalho ou documentos específicos. Você pode misturar níveis, por exemplo, um espaço de trabalho inteiro mais um único documento de outro lugar.

Selecionar um item pai concede acesso a tudo dentro dele. Se você selecionar um espaço de trabalho, não precisa também selecionar os documentos dentro dele.

Você pode alterar essa seleção depois pela página 'Aplicativos autorizados' nas configurações da sua conta do Grist, sem desconectar o cliente. Uma alteração pode levar até uma hora para chegar aos clientes já conectados, como Claude ou ChatGPT. Para aplicá-la imediatamente, desconecte e reconecte o Grist nas configurações do conector desse cliente.

Saiba mais sobre aplicativos conectados.

Ferramentas disponíveis

O servidor MCP do Grist expõe um conjunto de ferramentas para trabalhar com seus documentos, agrupadas em algumas categorias. As ferramentas agem em seu nome, então só podem acessar o que sua conta pode acessar. As permissões que você concede na tela de consentimento restringem ainda mais isso, permitindo limitar o que o conector pode fazer.

[!note] Nota Todo nome de ferramenta é prefixado com grist_ quando chamado (então list_docs é grist_list_docs). O prefixo é omitido nesta lista para facilitar a leitura.

Descoberta

Encontre o que você tem acesso.

list_orgs lista seus sites de equipe.
list_workspaces lista espaços de trabalho dentro de um site de equipe.
list_docs lista documentos dentro de um espaço de trabalho.
get_doc_info retorna metadados sobre um único documento.
get_user_profile retorna o nome e o e-mail da conta à qual você está conectado.
help retorna uma visão geral curta do que o servidor pode fazer.

Experimente perguntar:

"Quais documentos do Grist eu tenho?"
"Mostre-me tudo no meu site de equipe de Marketing."

Leitura de dados

Consulte e inspecione o conteúdo dos documentos.

query_document executa uma consulta em linguagem natural ou estilo SQL nas tabelas de um documento.
list_records retorna linhas de uma única tabela.
get_tables e get_table_columns descrevem a estrutura de um documento.
list_snapshots lista versões salvas mais antigas de um documento.
get_grist_access_rules_reference explica como funcionam as regras de acesso de um documento.

Experimente perguntar:

"Quantos negócios em aberto há no meu CRM?"
"Liste contatos com quem não falo há 90 dias."
"Qual é a receita total por cliente neste trimestre no meu documento de Faturas?"

Escrita de dados

Modifique registros.

add_records adiciona novas linhas.
update_records modifica linhas existentes pelo ID da linha.
remove_records exclui linhas.

Experimente perguntar:

"Adicione um novo cliente chamado Acme Corp ao meu CRM com o e-mail ops@acme.com."
"Marque a tarefa #42 como concluída no meu Rastreador de Projetos."
"Remova todas as linhas em Chamados onde o Status é 'Arquivado'."

Gerenciamento de documentos e esquema

Crie e reformule documentos.

create_doc cria um novo documento em um espaço de trabalho.
create_table e add_table_column estendem o esquema.
update_table_column altera o tipo de coluna, fórmula ou rótulo.

Outras ferramentas: rename_table, remove_table, remove_table_column.

Experimente perguntar:

"Crie um novo documento para controlar minhas despesas."
"Adicione uma coluna Prioridade a Tarefas com opções Baixa, Média, Alta."
"Renomeie a coluna Notas para Comentários no meu CRM."

Páginas e widgets

Gerencie as páginas e widgets de um documento.

get_pages lista as páginas de um documento.
add_page_widget adiciona um widget a uma página (Tabela, Cartão, Lista de Cartões, Gráfico, Calendário, Personalizado e assim por diante).
update_page_widget altera o título, a tabela, a configuração de exibição ou o layout de um widget.

Outras ferramentas: update_page, remove_page, get_page_widgets, remove_page_widget, get_page_widget_select_by_options, set_page_widget_select_by, get_available_custom_widgets.

Experimente perguntar:

"Adicione uma página de gráfico ao meu documento de Vendas mostrando receita por mês."
"Coloque uma Visualização de Cartão de Contatos na página Visão Geral."
"Remova a página Notas Internas do meu Rastreador de Projetos."

Anexos

Trabalhe com arquivos armazenados em um documento.

list_attachments lista os arquivos de um documento, com nome, tamanho e tipo.
get_attachment_url fornece um link de curta duração para baixar um arquivo.

Experimente perguntar:

"Quais arquivos estão anexados no meu documento de Despesas?"
"Dê-me um link de download para o recibo no meu documento de Despesas."

Exemplos de prompts

Estes exemplos usam Claude.ai. Na primeira vez que o Claude chama uma ferramenta do Grist, ele pede sua aprovação. Você pode escolher 'Sempre permitir' para pular o prompt dessa ferramenta em chamadas futuras.

tool-call-approval

Você pode usar o servidor MCP do Grist para:

Consultar dados estruturados em linguagem natural: “No meu documento CRM, quem tem uma tarefa aberta com vencimento nos próximos 7 dias?”
Atualizar registros em massa: “No meu documento Entregas, atualize todas as datas para seguir o formato ISO 8601.”
Criar um documento do zero: “Crie um novo documento chamado ‘Reviewer Sandbox’ com uma tabela Sample que tenha as colunas com tipos corretos: Name, Value, Created.”

Quando o assistente terminar, o documento novo ou atualizado estará pronto para abrir no Grist.

Tratamento de dados

Quando você chama uma ferramenta do Grist pelo seu cliente MCP, os dados retornados pela ferramenta são enviados ao provedor de IA do cliente para que o modelo possa usá-los na resposta.

O transporte é HTTPS/TLS de ponta a ponta.
O servidor MCP não armazena dados próprios. Cada requisição é autenticada com sua conta Grist existente e suas regras de acesso.
O token OAuth tem escopo limitado às permissões que você concedeu na conexão. Você pode revogá-lo a qualquer momento nas configurações da conta do Grist.

[!warning] Aviso Trate o conector como se estivesse compartilhando um documento com um colega. Qualquer coisa que você pedir ao cliente para ler ou escrever ficará visível para o provedor de IA dele.

Consulte a Política de Privacidade do Grist para detalhes.

FAQ

Quanto custa o servidor MCP do Grist?

O servidor MCP do Grist está atualmente disponível para todos os usuários do Grist sem custo adicional, no Grist Hospedado e na edição completa do Grist auto-hospedado, em todos os planos. Isso pode mudar no futuro.

Seu cliente MCP pode ter requisitos próprios (por exemplo, alguns clientes só permitem conectores personalizados em planos pagos). Isso depende do provedor, então consulte a página de preços deles para detalhes.

Como o servidor MCP trata meus dados?

Consulte a seção Tratamento de dados.

Posso ter vários conectores do Grist?

Sim. A maioria dos clientes MCP permite adicionar o mesmo servidor MCP mais de uma vez com nomes de conector diferentes, para que você possa manter conexões separadas (por exemplo, conectado com contas Grist diferentes). No Claude, a listagem de diretórios suporta apenas uma conexão, mas o caminho de conector personalizado não impede você de adicionar a mesma URL novamente com um nome diferente.

Como me conectar com uma conta Grist diferente?

Duas opções, disponíveis na maioria dos clientes:

Desconecte o Grist das configurações de conector do seu cliente e reconecte. Quando a tela de consentimento aparecer, entre com a outra conta.
Adicione o Grist como conector personalizado uma segunda vez com um nome diferente e entre com a outra conta durante a etapa de consentimento. As duas conexões ficam lado a lado.

Posso conectar meu Grist auto-hospedado?

Sim, desde que você esteja executando a edição completa do Grist. O Grist auto-hospedado expõe o mesmo endpoint MCP no seu próprio host: https://<your-grist-host>/api/mcp. Adicione essa URL ao seu cliente MCP da mesma forma que adicionaria qualquer outro servidor MCP e entre com sua conta Grist. Consulte Grist auto-hospedado para ativar o servidor e Conectando seu cliente MCP para as etapas de conexão.

Por que estou vendo um erro de “escopo ausente”?

Uma ferramenta tentou usar uma permissão que a conexão não possui. Por exemplo, se você aprovou apenas acesso de leitura, ferramentas de escrita como add_records se recusarão a executar.

Alguns clientes pedem que você aprove a permissão ausente imediatamente, após o que a ferramenta executa. Se o seu não fizer isso, desconecte o Grist nas configurações de conector do cliente e reconecte, aprovando o acesso que deseja permitir. Na página de configurações do conector, você também pode ver todas as ferramentas do Grist às quais o cliente tem acesso e ajustar quais exigem aprovação.

claude-connector-settings

Por que estou vendo um erro de “documento não encontrado”?

Geralmente um dos seguintes:

O documento foi excluído, movido ou renomeado.
Você não tem acesso ao documento com a conta que autorizou no seu cliente.
Você está pedindo ao cliente para procurar em um site de equipe diferente daquele onde o documento está.

Primeiro, verifique qual conta Grist você usou ao conectar. Se não tiver certeza, pergunte à IA algo como “em qual conta Grist estou conectado?” e ela informará o nome e o e-mail da conta conectada. Se você tiver várias contas Grist (por exemplo, uma pessoal e uma de trabalho), o documento pode estar em uma conta diferente. Abra docs.getgrist.com, confirme que o documento existe na conta que você usou para conectar e verifique se você tem pelo menos acesso de visualização.

Se não tiver certeza de qual conta está conectada, a correção mais rápida é desconectar o Grist nas configurações de conector do cliente e reconectar, entrando com a conta certa desta vez.

Se o documento estiver em um site de equipe diferente, peça à IA para listar seus sites de equipe primeiro com list_orgs.