Configure o MCP do Snowflake para o Notion

Seus Agentes personalizados e 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 de 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 um Agente personalizado 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 autorizaçã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 fazê-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 entrar 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 (recomendado). 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 de função primária explícito. 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 de funções do Snowflake, não adicione usuários manualmente fora desse processo.

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

Para questões de negócios governadas, você pode expor um Cortex Agent como a ferramenta que os membros usam. Ele mantém visualizações semânticas, consultas verificadas, Busca e orquestração em um só lugar. Um Cortex Agent é opcional. Se você criar um, use a especificação abaixo. Se você substituir um agente existente, certifique-se de que a substituição corresponda à sua 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, 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 selecionar 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 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, coordene com o administrador do seu espaço de trabalho Notion. Peça a ele 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 um URI de redirecionamento. Copie-o e envie-o para o administrador do Snowflake. Após o Snowflake criar o ID do cliente e o segredo, o administrador do espaço de trabalho pode concluir a configuração da conexão.

Use o URI de redirecionamento exatamente como o Notion o 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 corresponde às 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 o URI de redirecionamento corresponde exatamente, se a função é permitida e não bloqueada, se os tokens de atualização e PKCE estão ativados, e se tanto o endpoint de autorização quanto o de token usam o host de conta pública do Snowflake.

Esta etapa só é necessária se sua organização exigir uma política de rede. Peça ao proprietário de segurança ou de 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 de tempo de execução do workspace que valida a conexão, executa ferramentas e atualiza tokens

Esses caminhos 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 único de um navegador ou log 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 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 seu segredo correspondente com o administrador do seu espaço de trabalho Notion usando um canal seguro aprovado. O Snowflake fornece dois segredos válidos, para que você possa alterná-los sem tempo de inatividade. 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 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 concessõ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 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 receba respostas baseadas apenas nos dados que ela 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 acesso habitual do Okta ou SAML SSO da sua organização pode aparecer.

5. Reveja 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ção semântica usar como ponto de partida. Algumas perguntas de exemplo verificadas ajudam muito. Para um ponto de partida pronto, consulte o guia do Data Scout toolkit.

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 será solicitada a 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 alcance 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 SAML 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 inofensiva com uma resposta conhecida que deva usar 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 lhe foi atribuída.

Se você configurar um Agente personalizado, peça também a um Colegas de equipe com uma função mais restrita no Snowflake para testá-lo. Ele deve ver apenas os próprios dados, não os seus. Essa é a maneira mais rápida de confirmar que o agente está usando o acesso de cada pessoa em vez do acesso do construtor.

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

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

• "Do Snowflake, quais foram nossas inscrições totais no mês passado?"

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

Com um Agente personalizado, você geralmente pode pular "do Snowflake" assim que suas instruções deixarem claro quando usá-lo. Com seu Agente do Notion, nomear o Snowflake ajuda o agente a escolher a fonte correta.

Solicitações grandes podem levar mais tempo ou exceder o tempo limite. 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 expirando por si só não desconectará você.

Você precisará fazer login 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 é removida.

• Um administrador remove 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 uma pessoa for solicitada a fazer login novamente, isso não afetará ninguém, e a pessoa que construiu 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. Seu administrador de workspace pode não tê-la adicionado ainda, ou seu workspace pode limitar servidores personalizados. Peça ajuda ao seu administrador.

• Você é solicitado a fornecer um ID de cliente ou segredo. Você provavelmente escolheu a opção MCP personalizada. Volte e escolha o servidor Snowflake marcado como Gerenciado pelo espaço de trabalho em vez disso.

• 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ê faça 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 Colegas 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 um agendamento. Execuções agendadas e acionadas não têm uma pessoa conectada, portanto, ainda não podem usar o Snowflake com login individual.

• Você fez login, mas ele não conecta ou as ferramentas falham. Fazer login comprova quem você é, mas seu acesso ainda depende do seu acesso concedido 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 autorizaçõ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 pode não estar chegando ao servidor, ou uma regra de função ou de rede está 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. Use uma função exata 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ê pode alcançar 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 na sua sessão.

• Funcionava antes, e agora todos falham após uma alteração de segredo. O segredo do cliente foi rotacionado, 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, não pontos.

• Uma conta PrivateLink não pode se conectar. Contas PrivateLink precisam de uma configuração de rede extra. Peça ao seu administrador para confirmar 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.