Configure o MCP do Snowflake para o Notion

Seus Agentes personalizados e o Agente do Notion podem se conectar ao Snowflake por meio de um servidor MCP (Model Context Protocol) que o Snowflake executa. Depois de configurado, você pode perguntar ao seu agente sobre os dados do seu warehouse do Snowflake e obter respostas diretamente no Notion.

A configuração ocorre em etapas, e pessoas diferentes são responsáveis por cada uma:

• Um administrador do Snowflake configura a função, o warehouse e o servidor MCP gerenciado pelo Snowflake.

• Um proprietário ou administrador do espaço de trabalho do Notion configura a conexão MCP do Snowflake para o espaço de trabalho.

• Os membros do espaço de trabalho podem então se conectar ao MCP do Snowflake a partir de Agentes personalizados usando suas próprias credenciais do Snowflake, ou conectar o Snowflake diretamente ao seu Agente do Notion. As etapas 1 a 10 deste artigo são as mesmas para ambos os caminhos. Os caminhos se separam na etapa 11, dependendo de qual agente você deseja conectar.

• As ferramentas disponíveis podem variar de acordo com sua região de nuvem do Snowflake.

• O servidor MCP gerenciado do Snowflake não está disponível na China continental ou em regiões governamentais.

• Seu espaço de trabalho do Notion precisa estar no Plano Business ou no Plano Enterprise.

• Use o Notion na web ou no desktop. Este recurso não está disponível em dispositivos móveis.

• Sua empresa precisa de uma conta Snowflake.

• Para criar um Agente personalizado, você precisa de permissão para criar agentes em seu espaço de trabalho.

Antes que sua equipe possa conectar o Snowflake ao Notion, um administrador do Snowflake precisa configurar o acesso. Esta é a etapa mais complexa, e você só precisa realizá-la uma vez. Trabalhe com o administrador do seu espaço de trabalho do Notion: o Notion fornece um URI de redirecionamento, e o Snowflake fornece um ID de cliente OAuth e um segredo.

Você configurará uma função e um warehouse, criará o servidor MCP gerenciado pelo Snowflake, concederá a ele acesso aos recursos necessários, configurará o escopo OAuth e a integração de segurança, e adicionará uma política de rede se sua organização exigir.

Preencha esta planilha com o administrador do seu espaço de trabalho do Notion antes de começar. Os membros podem ignorá-la e fazer login com suas próprias contas Snowflake assim que a configuração for concluída.

O nome do host da conta usa hifens, não sublinhados. Certifique-se de que cada nome de objeto na URL do servidor corresponda ao nome de objeto correspondente no Snowflake.

Use uma função dedicada com privilégios mínimos e um warehouse aprovado sempre que possível.

Função restrita sem funções secundárias (recomendada). Este modelo é mais fácil de entender e auditar. Defina OAUTH_USE_SECONDARY_ROLES = NONE, especifique ALLOWED_ROLES_LIST e use o escopo do Notion session:role:<mcp_access_role>.

Funções secundárias padrão de um usuário (opcional). Use este modelo apenas quando o servidor precisar de privilégios herdados das DEFAULT_SECONDARY_ROLES do Snowflake de cada usuário. Defina OAUTH_USE_SECONDARY_ROLES = IMPLICIT, omita ALLOWED_ROLES_LIST e use um escopo explícito de função principal. O Snowflake não permite funções secundárias IMPLICIT com ALLOWED_ROLES_LIST, portanto, omita a lista de permissões ao usar este modelo.

Use uma função dedicada com privilégios mínimos para o servidor MCP sempre que possível.

Conceda essa função por meio do seu processo normal de gerenciamento de identidade. Se o Okta ou o SCIM gerenciarem a associação a funções do Snowflake, não adicione usuários manualmente fora desse processo.

Crie ou escolha uma base de dados e um esquema pertencentes à equipe que executará o servidor.

Para responder a perguntas sobre dados de negócios sujeitos a governança, você pode disponibilizar um Cortex Agent como ferramenta para os membros. Ele reúne visualizações semânticas, consultas verificadas, busca e orquestração em um só lugar. O Cortex Agent é opcional. Se você criar um, use a especificação abaixo. Se substituir um agente existente, confira se o novo agente corresponde à especificação aprovada.

Outros tipos de ferramentas MCP do Snowflake suportados incluem CORTEX_ANALYST_MESSAGE, CORTEX_SEARCH_SERVICE_QUERY, GENERIC e SYSTEM_EXECUTE_SQL.

Dê a cada ferramenta um nome e uma descrição claros. Explique quais dados ela cobre, quão detalhados são seus resultados e quando usá-la. Isso ajuda o agente a escolher a ferramenta certa.

O privilégio USAGE em um servidor MCP permite que uma função se conecte ao servidor e descubra suas ferramentas. Ele não concede à função acesso ao warehouse, ao agente, à visualização semântica, ao serviço de busca, ao procedimento armazenado nem aos dados subjacentes. Conceda à função acesso a cada recurso de que as ferramentas do servidor precisam.

Conceda acesso apenas aos recursos adicionais de que cada ferramenta precisa. Por exemplo, conceda SELECT em uma visualização semântica aprovada, USAGE em um serviço Cortex Search ou USAGE em uma função ou procedimento específico. Não conceda a função a PUBLIC nem adicione privilégios amplos para objetos atuais ou futuros.

Antes de configurar o OAuth, verifique o servidor MCP e suas concessões:

Configure o esquema MCP para anunciar a função exata que os membros devem solicitar:

Use um escopo de função explícito. Não use session:role:all. O Snowflake trata esse valor como a função primária padrão do usuário, não como acesso a todas as funções, e políticas para funções privilegiadas podem bloqueá-lo. Uma função explícita torna o acesso solicitado claro e mais fácil de verificar.

Antes de executar este SQL, converse com a administração do seu espaço de trabalho do Notion. Peça que adicionem a URL do servidor Snowflake ao formulário de configuração do MCP do espaço de trabalho e ativem Configurar a autenticação manualmente e Usar um cliente OAuth compartilhado pelo espaço de trabalho. O Notion gera uma URI de redirecionamento. Copie-a e envie-a para a administração do Snowflake. Depois que o Snowflake criar o ID e o segredo do cliente, a administração do espaço de trabalho poderá concluir a configuração da conexão.

Use a URI de redirecionamento exatamente como o Notion a fornece. Não adicione uma barra final nem parâmetros de consulta e não altere o host.

Definir IS_AGENTIC = TRUE marca as sessões criadas por meio desta integração como sessões de agente. A função IS_AGENT_ACTIVATED() do Snowflake retorna então TRUE, o que permite que o Snowflake aplique auditoria e governança específicas para agentes. Se você usar o modelo opcional de função secundária, defina OAUTH_USE_SECONDARY_ROLES = IMPLICIT e omita ALLOWED_ROLES_LIST.

O valor 7776000 segundos para a validade do token de atualização equivale a 90 dias. Antes de usá-lo, confirme se ele está em conformidade com as políticas de reautorização e rotação de tokens da sua organização. Para alterações de rotina, evite CREATE OR REPLACE SECURITY INTEGRATION. Substituir a integração pode interromper conexões existentes.

Para verificar a integração sem exibir seu segredo, execute:

Confirme se a integração está ativada, se a URI de redirecionamento corresponde exatamente, se a função é permitida e não está bloqueada, se os tokens de atualização e o PKCE estão ativados e se os pontos finais de autorização e de token usam o host público da conta do Snowflake.

Esta etapa só é necessária se sua organização exigir uma política de rede. Peça ao seu responsável pela segurança ou rede para aprovar os intervalos de saída atuais do Notion.

A integração OAuth deve permitir as duas rotas do Notion:

1. a rota da API que processa os retornos de chamada OAuth e troca os códigos de autorização

2. a rota de execução do espaço de trabalho que valida a conexão, executa ferramentas e atualiza tokens

Essas rotas podem usar endereços de saída diferentes do Notion. Se você permitir apenas o endereço usado durante a troca inicial de token, o login pode ter sucesso, mas a validação ou a atualização do token podem falhar. Use os intervalos de saída atuais e aprovados do Notion. Não adicione um endereço IP observado uma única vez em um navegador ou registro a uma lista de permissões de produção.

Anexe esta política de rede à integração OAuth, não a usuários individuais. Não altere suas políticas de conta para login no navegador, acesso VPN ou acesso à rede do usuário. Se uma política de rede bloquear uma solicitação de token, o Snowflake poderá retornar invalid_client. Esse erro não significa necessariamente que o ID do cliente ou o segredo estão incorretos.

Execute isto em uma planilha segura do Snowflake. O nome da integração diferencia maiúsculas de minúsculas e geralmente está em maiúsculas:

Compartilhe o ID do cliente e seu segredo correspondente com o administrador do seu espaço de trabalho do Notion usando um canal seguro aprovado. O Snowflake fornece dois segredos válidos, para que você possa fazer a rotação deles sem interrupção do serviço. Nunca cole nenhum dos segredos em documentação, chat, tickets ou controle de código-fonte.

Assim que o Snowflake estiver pronto, um proprietário ou administrador do espaço de trabalho adiciona o servidor uma vez para o espaço de trabalho. Os membros podem então encontrá-lo sem ver o segredo do cliente OAuth, estejam eles conectando o MCP do Snowflake a um Agente personalizado ou ao seu próprio Agente do Notion.

1. Vá para Configurações do espaço de trabalho.

2. Selecione Conexões → MCPs compartilhados do espaço de trabalho.

3. Selecione Novo MCP do espaço de trabalho.

Preencha estes campos e selecione Adicionar servidor MCP:

Após salvar, confirme se a nova linha aparece em Compartilhado com este espaço de trabalho e se Cliente OAuth do espaço de trabalho mostra Configurado.

O que esta configuração faz:

• Ajuda os membros a encontrar o servidor aprovado.

• Armazena o segredo do cliente OAuth uma única vez no armazenamento de conexões criptografado do Notion.

• Garante que os membros façam login com a URL do servidor, o cliente e os escopos que você aprovou.

• Não cria uma sessão compartilhada do Snowflake nem ignora os controles de acesso do Snowflake.

• Não conecta todos os membros automaticamente. Cada pessoa deve fazer login separadamente.

Se você remover esta configuração, novos membros não poderão mais encontrar o servidor. As conexões existentes ainda podem aparecer, portanto, coordene essa alteração com a revogação de permissões do Snowflake e a remoção de conexões existentes.

Assim que seus administradores tiverem a conexão MCP do Snowflake pronta, há duas maneiras de usá-la. Se você estiver configurando isso para uma equipe, comece pela 11A. Se você quiser apenas fazer suas próprias perguntas, pule para a 11B. Você pode usar as duas opções; são conexões separadas.

Um Agente personalizado oferece à sua equipe um único lugar para fazer perguntas sobre os dados do Snowflake. Você conecta o Snowflake uma vez, adiciona instruções sobre suas métricas e tabelas e compartilha o agente com sua equipe. Todas as pessoas que usarem o agente precisarão entrar no Snowflake com suas próprias credenciais. Assim, cada uma receberá respostas apenas com base nos dados que pode acessar.

Conectar o Snowflake a um Agente personalizado

1. Abra seu Agente personalizado ou crie um novo.

2. Acesse Configurações → Ferramentas e acesso.

3. Selecione Adicionar conexão e, em seguida, escolha o servidor Snowflake rotulado como Gerenciado pelo espaço de trabalho. Não selecione Servidor MCP personalizado nem insira a URL do servidor manualmente.

4. Faça login no Snowflake pelo navegador. Talvez você veja a tela de login habitual da sua organização pelo Okta ou SSO.

5. Revise e aprove a função do Snowflake solicitada.

6. Escolha quais ferramentas o agente pode usar. Deixe as ferramentas com capacidade de escrita e CORTEX_AGENT_RUN configuradas para solicitar aprovação até que você as tenha testado.

7. Selecione Conectar e confirme se a conexão aparece como Conectado.

Dê contexto ao agente

A conexão dá ao agente acesso ao Snowflake. Suas instruções explicam como sua empresa usa esses dados. Nas instruções do agente, descreva quais ferramentas usar para cada tipo de pergunta, como sua equipe define as principais métricas e por quais tabelas ou visualizações semânticas começar. Alguns exemplos de perguntas validadas ajudam muito. Para começar com algo pronto, consulte o guia do kit de ferramentas Data Scout.

Compartilhe o agente

Compartilhe o agente com sua equipe como faria com qualquer Agente personalizado. Na primeira vez que alguém fizer uma pergunta que precise do Snowflake, essa pessoa terá que fazer login com a própria conta do Snowflake. Não precisará informar um ID de cliente nem um segredo.

Se quiser fazer perguntas no seu chat, conecte o Snowflake ao seu Agente do Notion. Você faz login com sua própria conta do Snowflake, então o agente só acessa o que você tem permissão para ver.

1. Acesse Configurações → IA do Notion.

2. Em Servidores MCP, selecione Adicionar servidor MCP.

3. Selecione o servidor Snowflake rotulado como Gerenciado pelo espaço de trabalho. Não selecione Servidor MCP personalizado nem insira a URL do servidor manualmente.

4. Selecione Conectar.

5. Faça login no Snowflake pelo navegador. Talvez você veja a tela de login habitual da sua organização pelo Okta ou SSO.

6. Revise e aprove a função do Snowflake solicitada.

7. Quando seu navegador perguntar se deseja abrir o Notion, selecione Abrir Notion.

8. Confirme se o status do servidor é Conectado, não Requer autenticação.

Após conectar, o Snowflake aparece em Todas as fontes → Servidores MCP no chat.

1. Faça uma pergunta inofensiva, com resposta conhecida, que exija o uso do Snowflake.

2. Confirme se o agente usa o Snowflake e retorna um resultado.

3. Confirme que você não consegue acessar dados aos quais a função atribuída a você não dá acesso.

Se você configurar um Agente personalizado, peça também a uma pessoa da equipe com uma função mais restrita no Snowflake para testá-lo. Essa pessoa deve ver apenas os próprios dados, não os seus. Essa é a maneira mais rápida de confirmar que o agente usa o acesso de cada pessoa, e não o de quem criou o agente.

Para uma verificação mais profunda, peça ao seu administrador do Snowflake para confirmar seu usuário, função, warehouse e histórico de consultas. Um login bem-sucedido confirma sua identidade, mas não confirma se todas as permissões estão corretas.

Faça ao agente uma pergunta específica sobre seus dados do Snowflake. Por exemplo:

• "No Snowflake, quantas inscrições tivemos no total no mês passado?"

• "No Snowflake, quais foram nossas 10 contas com maior receita neste trimestre?"

Com um Agente personalizado, geralmente você pode omitir "no Snowflake" depois que as instruções deixarem claro quando usá-lo. Com seu Agente do Notion, mencionar o Snowflake ajuda o agente a escolher a fonte correta.

Solicitações grandes podem levar mais tempo ou expirar. Se isso acontecer, faça uma pergunta mais específica ou divida a solicitação em perguntas menores.

Na maioria das vezes, você permanece conectado sem fazer nada. O Snowflake usa tokens de acesso de curta duração, e o Notion os atualiza em segundo plano. Um token de acesso prestes a expirar, por si só, não desconecta você.

Você precisará entrar novamente se:

• Seu token de atualização expirar ou um administrador o revogar

• Um administrador substituir a integração OAuth ou o segredo do cliente

• Sua função no Snowflake for removida

• Um administrador remover a configuração do espaço de trabalho ou sua conexão

• Uma política de rede bloquear a atualização do token

Com um Agente personalizado, o login de cada pessoa é separado. Se uma pessoa precisar entrar novamente, isso não afetará mais ninguém, e a pessoa que criou o agente não precisará fazer nada.

Se você estiver fazendo a rotação do segredo do cliente: Use a rotação de dois segredos do Snowflake em vez de substituir a integração. Mantenha ambos os segredos válidos por tempo suficiente para atualizar e testar a configuração do espaço de trabalho antes de desativar o antigo.

ALTER SECURITY INTEGRATION <oauth_integration_name>
REFRESH OAUTH_CLIENT_SECRET_2;

• A conexão MCP do Snowflake não aparece na lista. Talvez o administrador do seu espaço de trabalho ainda não a tenha adicionado, ou o espaço de trabalho limite o uso de servidores personalizados. Peça ajuda ao administrador.

• Pedem que você informe um ID de cliente ou um segredo. Você provavelmente escolheu a opção de servidor MCP personalizado. Volte e selecione o servidor Snowflake marcado como Gerenciado pelo espaço de trabalho.

• Você é solicitado a fazer login novamente. Sua sessão do Snowflake pode ter expirado, ou um administrador pode ter atualizado a conexão. Faça login no Snowflake novamente.

• Você abriu um Agente personalizado e ele solicitou que você fizesse login no Snowflake. Isso é esperado na primeira vez. Cada pessoa que usa um Agente personalizado gerenciado precisa fazer login com suas próprias credenciais do Snowflake.

• Um colega de equipe obtém resultados diferentes do mesmo Agente personalizado. Isso é esperado. O agente usa o acesso ao Snowflake de cada pessoa, portanto, pessoas com funções diferentes veem dados diferentes.

• O Agente personalizado funciona no chat, mas não em execuções agendadas. As execuções agendadas e acionadas não têm ninguém conectado. Por isso, ainda não podem usar o Snowflake com login individual.

• Você fez login, mas a conexão não funciona ou as ferramentas falham. O login confirma sua identidade, mas seu acesso ainda depende das permissões no Snowflake. Peça ao administrador do Snowflake para confirmar se sua função permite acessar o servidor, o warehouse, o agente e os dados.

• O agente não consegue encontrar uma tabela. O agente só pode acessar os dados que sua conta do Snowflake pode acessar. Verifique suas permissões do Snowflake e inclua o nome da tabela em sua pergunta.

• Uma solicitação expira. Faça uma pergunta mais específica ou divida a solicitação em perguntas menores.

Esses erros geralmente vêm das configurações do Snowflake, não do Notion. Compartilhe-os com seu administrador do Snowflake.

• A URL do servidor parece duplicada, como https://https%3A... O endereço foi colado com um https:// extra na frente. Corrija para que a URL comece com apenas um https://.

• Você vê "This server does not support OAuth authentication." A integração de segurança não está configurada para OAuth ou a URL do servidor está incorreta. Peça ao seu administrador do Snowflake para verificar a integração de segurança OAuth e a URL do servidor.

• Você vê invalid_client ao fazer login ou atualizar. O ID do cliente ou o segredo está incorreto, ou o segredo foi alterado. Peça ao seu administrador o ID do cliente e o segredo atuais.

• O login funciona, mas falha logo em seguida. Sua função pode não ter acesso ao servidor, ou uma função ou regra de rede está bloqueando a sessão. Peça ao seu administrador para verificar suas permissões e políticas.

• Você vê "The role ALL requested has been explicitly blocked." A conexão solicitou todas as funções de uma vez (session:role:all), o que é bloqueado. Use uma função específica em vez disso, como session:role:analyst, com o nome real da sua função.

• Você vê um erro de redirecionamento (erro 390307). A URL de redirecionamento salva no Snowflake não corresponde à que o Notion usa. Peça ao seu administrador para definir a URL de redirecionamento na integração de segurança com o valor exato do Notion.

• Você vê o erro 390311 sobre um desafio de código inválido. Isso é uma incompatibilidade de PKCE. Peça ao seu administrador para confirmar se OAUTH_ENFORCE_PKCE está definido corretamente na integração de segurança.

• Você está conectado, mas nenhuma ferramenta aparece. Sua função pode estar sem USAGE no servidor MCP. Peça ao seu administrador para confirmar a permissão e, em seguida, execute DESCRIBE MCP SERVER para verificar a configuração.

• Você consegue acessar mais ou menos dados do que esperava. Funções secundárias alteram o que sua sessão pode ver. Verifique com seu administrador quais funções estão ativas em sua sessão.

• Funcionava antes, mas agora ninguém consegue se conectar após uma alteração do segredo. O segredo do cliente foi alterado, portanto, a conexão salva está desatualizada. Peça ao seu administrador o novo segredo e conecte-se novamente.

• Funcionava antes, e agora falha apenas para você. Uma função, permissão ou política pode ter mudado, ou sua sessão expirou. Faça login novamente e peça ao seu administrador para confirmar que seu acesso não mudou.

• Seu identificador de conta foi rejeitado. Use o formato organization-account com um hífen, como myorg-myaccount, e não com pontos.

• Uma conta PrivateLink não consegue se conectar. Contas PrivateLink precisam de configuração de rede adicional. Pergunte ao seu administrador se o PrivateLink permite a conexão com o Notion.

• O Snowflake não está disponível em execuções agendadas ou acionadas. Nessas execuções, ninguém faz login. Por isso, elas ainda não podem usar o login individual. Faça sua solicitação no chat.

• Você vê oauth_security_error após fazer login pelo navegador. Uma política de rede no nível da conta pode estar bloqueando a solicitação. Seu administrador pode confirmar executando:

• O login parece funcionar, mas você recebe um erro de função, mesmo com o escopo correto. Sua função padrão pode estar bloqueada, por exemplo, ACCOUNTADMIN ou uma função incluída na BLOCKED_ROLES_LIST. Seu administrador pode verificar e corrigir isso:

Estes comandos somente para leitura ajudam seu administrador a confirmar a configuração sem alterar nada. Execute-os no Snowflake.

Use estes guias do Snowflake para concluir a configuração:

• Servidor MCP gerenciado pelo Snowflake

• Criar uma integração de segurança OAuth do Snowflake

• OAuth do Snowflake para clientes personalizados

• Visão geral do OAuth do Snowflake

• Identificadores de conta do Snowflake

• Agentes personalizados

• Conexões MCP para Agentes personalizados

• Conecte servidores MCP ao seu Agente do Notion

• Práticas recomendadas de segurança para conexões de agentes