Configure o MCP do Snowflake para o Notion

Seus Agentes personalizados e seu Agente do Notion podem se conectar ao Snowflake por meio de um servidor MCP (Model Context Protocol) gerenciado pelo Snowflake. Depois de configurar a conexão, você pode perguntar ao seu agente sobre os dados do seu warehouse do Snowflake e receber 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 se conectar ao MCP do Snowflake por meio 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 iguais nos dois casos. A partir da etapa 11, siga as instruções para o agente que você quer 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 no Snowflake.

• Para criar um Agente personalizado, você precisa de permissão para criar agentes no 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ê vai 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 a sua organização exigir.

Preencha esta planilha com o administrador do seu espaço de trabalho do Notion antes de começar. Depois que a configuração estiver pronta, os membros podem pular essa etapa e entrar com suas próprias contas no Snowflake.

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 dos privilégios herdados das DEFAULT_SECONDARY_ROLES de cada usuário no Snowflake. Defina OAUTH_USE_SECONDARY_ROLES = IMPLICIT, omita ALLOWED_ROLES_LIST e use um escopo explícito para a função principal. O Snowflake não permite funções secundárias IMPLICIT com ALLOWED_ROLES_LIST. Por isso, omita a lista de funções permitidas 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 habitual de gerenciamento de identidade. Se o Okta ou o SCIM gerenciarem a atribuição de funções aos usuários no Snowflake, não adicione usuários manualmente fora desse processo.

Crie ou escolha uma base de dados e um esquema sob responsabilidade da equipe que vai operar 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 aceitos pelo MCP do Snowflake 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, agente, visualização semântica, serviço de Busca, procedimento armazenado ou dados subjacentes. Conceda à função acesso a cada recurso que as ferramentas do servidor precisam.

Conceda acesso apenas aos recursos adicionais 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 para PUBLIC nem adicione privilégios amplos para objetos atuais ou futuros.

Antes de configurar o OAuth, verifique o servidor MCP e as permissões concedidas a ele:

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 interpreta esse valor como a função principal padrão do usuário, não como acesso a todas as funções. Além disso, políticas para funções privilegiadas podem bloqueá-lo. Uma função explícita deixa claro qual acesso foi solicitado e facilita a verificação.

Antes de executar este SQL, fale com o administrador do seu espaço de trabalho do Notion. Peça para inserir a URL do servidor Snowflake no formulário de configuração MCP do espaço de trabalho e ativar 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 ao administrador do Snowflake. Depois que o Snowflake criar o ID do cliente e o segredo, o administrador 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 ou 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 de validade do token de atualização de 7776000 segundos 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 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 ambas as rotas do Notion:

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

2. a rota do ambiente 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 a uma lista de permissões de produção um endereço IP observado uma única vez em um navegador ou registro.

Anexe esta política de rede à integração OAuth, não a usuários individuais. Não altere as políticas que se aplicam a toda a conta para login pelo navegador, acesso por VPN ou acesso dos usuários à rede. 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 alterná-los sem interromper o serviço. Nunca cole nenhum dos segredos em documentação, chat, tickets ou controle de versão.

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 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 das permissões concedidas no Snowflake e a remoção das 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 quiser apenas fazer suas próprias perguntas, pule para a 11B. Você pode seguir os dois caminhos: são conexões separadas.

Um Agente personalizado oferece à sua equipe um único lugar para fazer perguntas sobre 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. Todos que o utilizarem precisarão fazer login no Snowflake com suas próprias credenciais. Assim, cada pessoa receberá respostas baseadas apenas nos dados que tem permissão para ver.

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 em seu navegador. O login habitual do Okta ou SSO da sua organização pode aparecer.

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 Conectada.

Forneça contexto ao agente

A conexão dá ao agente acesso ao Snowflake. Suas instruções dizem a ele como sua empresa usa esses dados. Nas instruções do agente, descreva quais ferramentas usar para quais tipos de perguntas, como sua equipe define as principais métricas e quais tabelas ou visualizações semânticas usar como ponto de partida. Alguns exemplos de perguntas verificadas ajudam muito. Para um ponto de partida 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, o agente vai pedir que essa pessoa faça login com a própria conta do Snowflake. Ela não precisará informar um ID de cliente nem um segredo.

Se você quiser fazer suas próprias perguntas em seu próprio chat, conecte o Snowflake ao seu Agente do Notion. Você faz login com sua própria conta do Snowflake, para que seu agente acesse apenas 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 em seu navegador. O login habitual do Okta ou SSO da sua organização pode aparecer.

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 simples, cuja resposta você já saiba e 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 além daqueles permitidos pela função que lhe foi atribuída.

Se você configurou 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:

• “Do Snowflake, qual foi o total de cadastros no mês passado?”

• “Do Snowflake, quais foram nossas 10 contas de maior receita neste trimestre?”

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

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. O simples fato de um token de acesso estar prestes a expirar não desconectará 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 bloqueia a atualização do token

Com um Agente personalizado, o login de cada pessoa é separado. Se for solicitado que uma pessoa faça login novamente, isso não afeta ninguém, e a pessoa que criou o agente não precisa fazer nada.

Se você estiver rotacionando o 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 Snowflake MCP não está listada. O administrador do seu espaço de trabalho pode ainda não tê-la adicionado, ou seu espaço de trabalho pode limitar o uso de servidores personalizados. Peça ajuda ao seu administrador.

• O sistema pede um ID de cliente ou um segredo. Você provavelmente escolheu a opção de servidor MCP personalizado. Volte e escolha o servidor Snowflake identificado como Gerenciado pelo espaço de trabalho.

• Você precisa 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 pediu que você fizesse login no Snowflake. Isso é normal na primeira vez. Cada pessoa que usa um Agente personalizado gerenciado precisa fazer login com as próprias credenciais do Snowflake.

• Uma pessoa da equipe obtém resultados diferentes ao usar o mesmo Agente personalizado. Isso é normal. O agente usa o acesso ao Snowflake de cada pessoa. Por isso, quem tem funções diferentes vê dados diferentes.

• O Agente personalizado funciona no chat, mas não quando é agendado. As execuções agendadas e acionadas não têm uma pessoa conectada. 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. Fazer login comprova quem você é, mas seu acesso ainda depende de suas permissões no Snowflake. Peça ao seu administrador do Snowflake para confirmar se sua função pode acessar o servidor, o warehouse, o agente e os dados.

• O agente não consegue encontrar uma tabela. O agente pode acessar apenas 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 atinge o tempo limite. Faça uma pergunta mais específica ou divida sua 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 talvez não tenha acesso ao servidor, ou uma função ou regra de rede pode estar 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, como session:role:analyst, substituindo pelo nome 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 falha para todos 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 se 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, não há ninguém com login ativo. Por isso, elas ainda não podem usar o login individual. Execute 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 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