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) 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 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 para as duas opções. Na etapa 11, as instruções mudam conforme 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 Snowflake.

• Para criar um Agente personalizado, você precisa de autorizaçã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. Essa é a etapa mais complexa, mas você só precisa realizá-la uma vez. Trabalhe com o administrador do seu espaço de trabalho do Notion: o Notion fornece uma 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 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 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 habitual de gerenciamento de identidade. Se o Okta ou o SCIM gerenciam a atribuição de funções no Snowflake, não adicione usuários manualmente fora desse processo.

Crie ou escolha uma base de dados e um esquema que pertençam à equipe responsável pelo servidor.

Para perguntas sobre dados empresariais sujeitos a governança, você pode disponibilizar um Cortex Agent como ferramenta para os membros. Ele reúne visualizações semânticas, consultas verificadas, Search 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 dá à função acesso ao warehouse, ao agente, à visualização semântica, ao serviço Cortex Search, 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 conceda privilégios amplos sobre 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 indicar 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 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, combine os próximos passos com o administrador do seu espaço de trabalho do Notion. Peça que ele insira a URL do servidor Snowflake no formulário de configuração do MCP do espaço de trabalho e ative 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 e o segredo do cliente, 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 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 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 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 tokens, o login poderá funcionar, mas a validação ou a atualização dos tokens poderá falhar. Use os intervalos de saída atuais e aprovados do Notion. Não adicione à 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 suas políticas de conta para login no navegador, acesso VPN ou acesso de 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 o 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 tempo de inatividade. 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 do 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 você quiser apenas fazer suas próprias perguntas, pule para a 11B. Você pode fazer ambos; 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, para que cada pessoa obtenha respostas baseadas apenas nos dados que têm 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 pelo navegador. A tela de login habitual da sua organização, pelo Okta ou por SSO, 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 Conectado.

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 da mesma forma que você compartilha qualquer Agente personalizado. Na primeira vez que alguém fizer uma pergunta que precise do Snowflake, essa pessoa receberá uma solicitação para fazer login com sua própria conta do Snowflake. Não será solicitado um ID de cliente ou 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 tenha acesso apenas ao 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. A tela de login habitual da sua organização, pelo Okta ou por SSO, pode aparecer.

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

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 cuja resposta você já conhece e que exija consultar o Snowflake.

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

3. Confirme que você não consegue acessar dados fora da função que recebeu.

Se você configurou um Agente personalizado, peça também a um colega de 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 o criou.

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, quantos cadastros tivemos no total 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" assim que suas 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. 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ê precisar fazer a rotação do segredo do cliente: Use a rotação de dois segredos do Snowflake em vez de substituir a integração. Mantenha os dois 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 está listada. O administrador do seu espaço de trabalho pode ainda não tê-la adicionado, ou seu espaço de trabalho pode restringir o uso de servidores personalizados. Peça ajuda ao seu administrador.

• Você precisa informar 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ê recebe uma solicitação para 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. 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 é estabelecida 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 expira. 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 pode não ter 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ê "A função ALL solicitada foi explicitamente bloqueada." A conexão solicitou todas as funções de uma vez (session:role:all), o que é bloqueado. Em vez disso, use uma função específica, como session:role:analyst, substituindo o exemplo pelo 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 parou de funcionar para todos após a troca do segredo. O segredo do cliente foi alterado, então a conexão salva está desatualizada. Peça ao seu administrador o novo segredo e conecte-se novamente.

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

• Seu identificador de conta foi rejeitado. Use o formato organization-account com um hífen, como myorg-myaccount, e não 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. Essas execuções não possuem uma pessoa conectada, portanto, 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