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) gerenciado pelo Snowflake. Depois da configuração, você pode perguntar ao seu agente sobre os dados do seu warehouse do Snowflake e receber as 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 do espaço de trabalho do Notion ou administrador 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. A partir da etapa 11, siga as instruções para o agente que você quer conectar.

• As ferramentas disponíveis podem variar conforme a região da nuvem do Snowflake.

• O servidor MCP gerenciado pelo 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 conecte o Snowflake ao Notion, um administrador do Snowflake precisa configurar o acesso. Essa é a etapa mais trabalhosa, mas só precisa ser feita uma vez. Coordene a configuração com o administrador do 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 e conceder a ele acesso aos recursos necessários. Depois, vai configurar o escopo OAuth e a integração de segurança. Se sua organização exigir, também vai adicionar uma política de rede.

Preencha esta planilha com o administrador do espaço de trabalho do Notion antes de começar. Os membros podem pular esta etapa e entrar com suas próprias contas Snowflake quando a configuração estiver pronta.

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 cada usuário (opcional). Use este modelo apenas quando o servidor precisar dos privilégios herdados de 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 da função principal. O Snowflake não permite funções secundárias IMPLICIT com ALLOWED_ROLES_LIST. Por isso, não inclua a lista de funções permitidas neste 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 pertencentes à equipe que vai executar o servidor.

Para perguntas de negócios que exigem governança de dados, 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 identifique as ferramentas disponíveis. Ele não dá à 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 necessário para as ferramentas do servidor.

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 suas concessões:

Configure o esquema MCP para indicar exatamente qual função 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 está sendo solicitado e facilita a verificação.

Antes de executar este SQL, alinhe os próximos passos com quem administra seu espaço de trabalho do Notion. Peça a essa pessoa que 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 no espaço de trabalho. O Notion gera um URI de redirecionamento. Copie-o e envie-o para o 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 o URI de redirecionamento exatamente como o Notion o fornece. Não adicione uma barra ao 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 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 está bloqueada, se os tokens de atualização e o PKCE estão ativados e se tanto o ponto final de autorização quanto o 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 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 um endereço IP usado uma única vez, obtido de 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 as políticas de toda a sua conta para login no 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 estejam 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 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 criptografado de conexões 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. Por isso, 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 você quiser apenas fazer suas próprias perguntas, pule para a 11B. Você pode fazer as duas coisas; 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 pelo navegador. Talvez apareça a tela de login via Okta ou SAML SSO que sua organização costuma usar.

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. Algumas perguntas de exemplo 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, terá que entrar com a própria conta do Snowflake. Não será necessário 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 pelo navegador. Talvez apareça a tela de login via Okta ou SAML SSO que sua organização costuma usar.

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 além dos permitidos pela função que lhe foi atribuída.

Se você configurar um Agente personalizado, peça também a alguém da equipe com uma função mais restrita no Snowflake para testá-lo. Essa pessoa deve ver apenas os dados a que tem acesso, 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:

• “Segundo o Snowflake, quantas inscrições tivemos no mês passado?”

• “Segundo o Snowflake, quais foram nossas 10 contas com maior receita neste trimestre?”

Com um Agente personalizado, geralmente você pode omitir “do Snowflake” quando as instruções já 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 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ê continua conectado sem precisar fazer nada. O Snowflake usa tokens de acesso de curta duração, e o Notion os atualiza em segundo plano. O vencimento de um token de acesso, 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 bloqueia 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á as outras, e a pessoa que criou o agente não precisa fazer nada.

Se você for 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 até atualizar e testar a configuração do espaço de trabalho. Só então desative 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 servidores personalizados. Peça ajuda ao seu administrador.

• Pediram que você informe 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 é 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 com o 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, portanto, 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.

• O tempo limite de uma solicitação é excedido. 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 restrição de função ou 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 única função específica, 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 na 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, em vez de 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