Snowflake Cortex AI

Um servidor para Snowflake que fornece ferramentas para seus recursos Cortex AI, incluindo Search, Analyst e Complete.

Documentação

[DEPRECATED] Servidor Snowflake Cortex AI Model Context Protocol (MCP)

[!CAUTION] Este projeto está obsoleto e não é mais mantido. Migre para o Servidor MCP oficial da Snowflake. O servidor oficial é ativamente desenvolvido, totalmente suportado pela Snowflake e continua adicionando novos recursos.

Este servidor MCP comunitário anteriormente fornecia ferramentas para Snowflake Cortex AI, gerenciamento de objetos e orquestração SQL. Ele não é mais suportado. Para todos os casos de uso novos e existentes, use o Servidor MCP oficial da Snowflake.


Documentação legada (apenas para referência)

O servidor MCP suportava os seguintes recursos:

  • Cortex Search: Consulte dados não estruturados no Snowflake, comumente usados em aplicações de Geração Aumentada por Recuperação (RAG).
  • Cortex Analyst: Consulte dados estruturados no Snowflake por meio de modelagem semântica avançada.
  • Cortex Agent: Orquestrador agêntico para recuperação de dados estruturados e não estruturados.
  • Gerenciamento de Objetos: Execute operações básicas nos objetos mais comuns do Snowflake, como criação, exclusão, atualização e muito mais.
  • Execução SQL: Execute SQL gerado por LLM gerenciado por permissões configuradas pelo usuário.
  • Consulta de Visualizações Semânticas: Descubra e consulte Visualizações Semânticas do Snowflake.

Introdução

Configuração do Serviço

Um arquivo de configuração simples é usado para direcionar todas as ferramentas. Um exemplo pode ser visto em services/configuration.yaml e um modelo está abaixo. O caminho para este arquivo de configuração será passado para o servidor e o conteúdo será usado para criar ferramentas do servidor MCP na inicialização.

Serviços Cortex

Muitos serviços Cortex Agent, Search e Analyst podem ser adicionados. Descrições ideais são altamente descritivas e mutuamente exclusivas. Somente os serviços Cortex explicitamente listados estarão disponíveis como ferramentas no cliente MCP.

Outros Serviços

Outros serviços incluem ferramentas para gerenciamento de objetos, execução de consultas e uso de visualizações semânticas. Esses grupos de ferramentas podem ser habilitados definindo-os como True na seção other_services do arquivo de configuração.

Permissões de Declarações SQL

A seção sql_statement_permissions garante que apenas declarações aprovadas sejam executadas em qualquer ferramenta com acesso para alterar objetos do Snowflake. A lista contém tipos de expressões SQL. Aqueles marcados como True são permitidos, enquanto aqueles marcados como False não são permitidos. Consulte Execução SQL para exemplos de cada tipo de expressão.

agent_services: # List all Cortex Agent services
  - service_name: <service_name>
    description: > # Describe contents of the agent service
      <Agent service that ...>
    database_name: <database_name>
    schema_name: <schema_name>
  - service_name: <service_name>
    description: > # Describe contents of the agent service
      <Agent service that ...>
    database_name: <database_name>
    schema_name: <schema_name>
search_services: # List all Cortex Search services
  - service_name: <service_name>
    description: > # Describe contents of the search service
      <Search services that ...>
    database_name: <database_name>
    schema_name: <schema_name>
  - service_name: <service_name>
    description: > # Describe contents of the search service
      <Search services that ...>
    database_name: <database_name>
    schema_name: <schema_name>
analyst_services: # List all Cortex Analyst semantic models/views
  - service_name: <service_name> # Create descriptive name for the service
    semantic_model: <semantic_yaml_or_view> # Fully-qualify semantic YAML model or Semantic View
    description: > # Describe contents of the analyst service
      <Analyst service that ...>
  - service_name: <service_name> # Create descriptive name for the service
    semantic_model: <semantic_yaml_or_view> # Fully-qualify semantic YAML model or Semantic View
    description: > # Describe contents of the analyst service
      <Analyst service that ...>
other_services: # Set desired tool groups to True to enable tools for that group
  object_manager: True # Perform basic operations against Snowflake's most common objects such as creation, dropping, updating, and more.
  query_manager: True # Run LLM-generated SQL managed by user-configured permissions.
  semantic_manager: True # Discover and query Snowflake Semantic Views and their components.
sql_statement_permissions: # List SQL statements to explicitly allow (True) or disallow (False).
  # - All: True # To allow everything, uncomment and set All: True.
  - Alter: True
  - Command: True
  - Comment: True
  - Commit: True
  - Copy: True
  - Create: True
  - Delete: True
  - Describe: True
  - Drop: True
  - Insert: True
  - Merge: True
  - Rollback: True
  - Select: True
  - Transaction: True
  - TruncateTable: True
  - Unknown: False # To allow unknown or unmapped statement types, set Unknown: True.
  - Update: True
  - Use: True

[!NOTE] Versões anteriores do arquivo de configuração suportavam especificar valores explícitos para colunas e limite para cada serviço Cortex Search. Em vez disso, agora eles são exclusivamente dinâmicos com base no prompt do usuário. Se não for especificado, as search_columns padrão de um serviço de pesquisa serão retornadas com um limite de 10.

Conectando ao Snowflake

O servidor MCP usa o Conector Python do Snowflake para todos os métodos de autenticação e conexão. Consulte a documentação oficial do Snowflake para opções abrangentes de autenticação e práticas recomendadas.

O servidor MCP honra as permissões RBAC atribuídas à função especificada (conforme passado nos parâmetros de conexão) ou à função padrão do usuário (se nenhuma função for passada para conectar).

Os parâmetros de conexão podem ser passados como argumentos de CLI e/ou variáveis de ambiente. O servidor suporta todos os métodos de autenticação disponíveis no Conector Python do Snowflake, incluindo:

  • Autenticação por nome de usuário/senha
  • Autenticação por par de chaves
  • Autenticação OAuth
  • Single Sign-On (SSO)
  • Autenticação multifator (MFA)

Parâmetros de Conexão

Os parâmetros de conexão podem ser passados como argumentos de CLI e/ou variáveis de ambiente:

ParâmetroArgumentos de CLIVariável de AmbienteDescrição
Account--accountSNOWFLAKE_ACCOUNTIdentificador da conta (ex.: xy12345.us-east-1)
Host--hostSNOWFLAKE_HOSTURL do host do Snowflake
User--user, --usernameSNOWFLAKE_USERNome de usuário para autenticação
Password--passwordSNOWFLAKE_PASSWORDSenha ou token de acesso programático
Role--roleSNOWFLAKE_ROLEFunção a ser usada para conexão
Warehouse--warehouseSNOWFLAKE_WAREHOUSEWarehouse a ser usado para consultas
Passcode in Password--passcode-in-password-Se o passcode está embutido na senha
Passcode--passcodeSNOWFLAKE_PASSCODEPasscode MFA para autenticação
Private Key--private-keySNOWFLAKE_PRIVATE_KEYChave privada para autenticação por par de chaves
Private Key File--private-key-fileSNOWFLAKE_PRIVATE_KEY_FILECaminho para o arquivo de chave privada
Private Key Password--private-key-file-pwdSNOWFLAKE_PRIVATE_KEY_FILE_PWDSenha para chave privada criptografada
Authenticator--authenticator-Tipo de autenticação (padrão: snowflake)
Connection Name--connection-name-Nome da conexão do arquivo connections.toml (ou config.toml)

[!WARNING] Aviso de Descontinuação: Os argumentos de CLI --account-identifier e --pat, bem como a variável de ambiente SNOWFLAKE_PAT, estão obsoletos e serão removidos em uma versão futura. Use --account e --password (ou SNOWFLAKE_ACCOUNT e SNOWFLAKE_PASSWORD).

Configuração de Transporte

O servidor MCP suporta múltiplos mecanismos de transporte. Para informações detalhadas sobre transportes MCP, consulte Protocolos de Transporte FastMCP.

TransporteDescriçãoCaso de Uso
stdioEntrada/saída padrão (padrão)Desenvolvimento local, integração com cliente MCP
sse (legado)Server-Sent EventsAplicações de streaming
streamable-httpTransporte HTTP transmissívelImplantações em contêineres, servidores remotos

Uso

# Default stdio transport
uvx snowflake-labs-mcp --service-config-file config.yaml

# HTTP transport with custom endpoint
uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http --endpoint /my-endpoint

# For containers (uses streamable-http on port 9000)
uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http --endpoint /snowflake-mcp

Personalizações de Transporte

Personalizações de servidor disponíveis para transportes sse e streamable-http:

ParâmetroArgumento de CLIVariável de AmbientePadrão
Host--server-hostSNOWFLAKE_MCP_HOST"0.0.0.0"
Port--portSNOWFLAKE_MCP_PORT9000
Endpoint--endpointSNOWFLAKE_MCP_ENDPOINT/mcp
Log de Depuração--verboseSNOWFLAKE_MCP_VERBOSEfalse

Exemplo:

export SNOWFLAKE_MCP_ENDPOINT="/my-mcp"
uvx snowflake-labs-mcp --service-config-file config.yaml --transport streamable-http

Uso com Clientes MCP

O servidor MCP é agnóstico de cliente e funcionará com a maioria dos Clientes MCP que suportam funcionalidade básica para ferramentas MCP e (opcionalmente) recursos. Abaixo estão exemplos para instalação local. Para conectar a implantações em contêineres, consulte Conectando Clientes MCP a Contêineres.

Claude Desktop

Para integrar este servidor com o Claude Desktop como Cliente MCP, adicione o seguinte à configuração do servidor do seu aplicativo. Por padrão, isso está localizado em:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Defina o caminho para o arquivo de configuração do serviço e configure seu método de conexão:

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "command": "uvx",
      "args": [
        "snowflake-labs-mcp",
        "--service-config-file",
        "<path_to_file>/tools_config.yaml",
        "--connection-name",
        "default"
      ]
    }
  }
}

Cursor

Registre o servidor MCP no Cursor abrindo o Cursor e navegando para Configurações -> Configurações do Cursor -> MCP. Adicione o seguinte:

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "command": "uvx",
      "args": [
        "snowflake-labs-mcp",
        "--service-config-file",
        "<path_to_file>/tools_config.yaml",
        "--connection-name",
        "default"
      ]
    }
  }
}

Adicione o servidor MCP como contexto no chat.

Para solucionar problemas de servidor no Cursor, visualize os logs abrindo o painel de Saída e selecionando Cursor MCP no menu suspenso.

fast-agent

Atualize a seção do servidor mcp fastagent.config.yaml com o caminho do arquivo de configuração e o nome da conexão:

# MCP Servers
mcp:
    servers:
        mcp-server-snowflake:
            command: "uvx"
            args: ["snowflake-labs-mcp", "--service-config-file", "<path_to_file>/tools_config.yaml", "--connection-name", "default"]

Microsoft Visual Studio Code + GitHub Copilot

Para pré-requisitos, configuração do ambiente, guia passo a passo e instruções, consulte este blog.

Codex

Registre o servidor MCP no codex adicionando o seguinte a ~/.codex/config.toml

[mcp_servers.mcp-server-snowflake]
command = "uvx"
args = [
    "snowflake-labs-mcp",
    "--service-config-file",
    "<path_to_file>/tools_config.yaml",
    "--connection-name",
    "default"
]

Após a edição, o snowflake mcp deve aparecer na saída de codex mcp list executado no terminal.

Implantação em Contêiner

Implante o servidor MCP como um contêiner para acesso remoto ou ambientes de produção. Este guia fornece instruções passo a passo para implantações Docker e Docker Compose.

Implantação Docker

Siga estas etapas para implantar o servidor MCP usando Docker:

Etapa 1: Preparar Arquivo de Configuração

Crie um diretório para a configuração do MCP e copie o modelo:

mkdir -p ${HOME}/.mcp/
cp services/configuration.yaml ${HOME}/.mcp/tools_config.yaml

Etapa 2: Configurar Serviços

Edite o arquivo de configuração para corresponder ao seu ambiente:

# Edit the configuration file as needed
# Update service names, database/schema references, and enable desired features
nano ${HOME}/.mcp/tools_config.yaml

Etapa 3: Construir Imagem do Contêiner

Construa a imagem Docker a partir do Dockerfile fornecido:

docker build -f docker/server/Dockerfile -t mcp-server-snowflake .

Etapa 4: Definir Variáveis de Ambiente

Configure seus parâmetros de conexão do Snowflake. Escolha um dos seguintes métodos de autenticação:

Autenticação por Nome de Usuário/Senha:

export SNOWFLAKE_ACCOUNT=<your_account>
export SNOWFLAKE_USER=<your_username>
export SNOWFLAKE_PASSWORD=<your_password>

Autenticação por Par de Chaves:

export SNOWFLAKE_ACCOUNT=<your_account>
export SNOWFLAKE_USER=<your_username>
export SNOWFLAKE_PRIVATE_KEY="$(cat <path_to_private_key.p8>)"
export SNOWFLAKE_PRIVATE_KEY_FILE_PWD=<your_key_password>

Etapa 5: Executar Contêiner

Inicie o contêiner com sua configuração e variáveis de ambiente:

Para Autenticação por Nome de Usuário/Senha:

docker run -d \
  --name mcp-server-snowflake \
  -p 9000:9000 \
  -e SNOWFLAKE_ACCOUNT=${SNOWFLAKE_ACCOUNT} \
  -e SNOWFLAKE_USER=${SNOWFLAKE_USER} \
  -e SNOWFLAKE_PASSWORD=${SNOWFLAKE_PASSWORD} \
  -v ${HOME}/.mcp/tools_config.yaml:/app/services/tools_config.yaml:ro \
  mcp-server-snowflake

Para Autenticação por Par de Chaves:

docker run -d \
  --name mcp-server-snowflake \
  -p 9000:9000 \
  -e SNOWFLAKE_ACCOUNT=${SNOWFLAKE_ACCOUNT} \
  -e SNOWFLAKE_USER=${SNOWFLAKE_USER} \
  -e SNOWFLAKE_PRIVATE_KEY="${SNOWFLAKE_PRIVATE_KEY}" \
  -e SNOWFLAKE_PRIVATE_KEY_FILE_PWD=${SNOWFLAKE_PRIVATE_KEY_FILE_PWD} \
  -v ${HOME}/.mcp/tools_config.yaml:/app/services/tools_config.yaml:ro \
  mcp-server-snowflake

Etapa 6: Verificar Implantação

Verifique se o contêiner está em execução e acessível:

# Check container status
docker ps

# Check container logs
docker logs mcp-server-snowflake

# Test endpoint (should return MCP server info)
curl http://localhost:9000/snowflake-mcp

Implantação Docker Compose

Siga estas etapas para uma implantação simplificada usando Docker Compose:

Etapa 1: Preparar Arquivo de Configuração

Crie o diretório de configuração e copie o modelo:

mkdir -p ${HOME}/.mcp/
cp services/configuration.yaml ${HOME}/.mcp/tools_config.yaml

Etapa 2: Configurar Serviços

Edite o arquivo de configuração para corresponder ao seu ambiente:

# Update service configurations as needed
nano ${HOME}/.mcp/tools_config.yaml

Etapa 3: Definir Variáveis de Ambiente

Configure seus parâmetros de conexão do Snowflake:

export SNOWFLAKE_ACCOUNT=<your_account>
export SNOWFLAKE_USER=<your_username>
# For username/password auth:
export SNOWFLAKE_PASSWORD=<your_password>
# For key pair auth, also set:
# export SNOWFLAKE_PRIVATE_KEY="$(cat <path_to_private_key.p8>)"
# export SNOWFLAKE_PRIVATE_KEY_FILE_PWD=<your_key_password>

Etapa 4: Iniciar Serviços

Inicie o contêiner usando Docker Compose:

docker-compose up -d

Etapa 5: Verificar Implantação

Verifique se os serviços estão em execução:

# Check service status
docker-compose ps

# View logs
docker-compose logs

# Test endpoint
curl http://localhost:9000/snowflake-mcp

Conectando Clientes MCP a Contêineres

Depois que seu servidor MCP estiver em execução em um contêiner, você pode conectar vários clientes MCP a ele. A configuração de conexão é a mesma em todos os clientes - apenas o formato da configuração difere.

Formato da URL de Conexão:

  • Implantação local: http://localhost:9000/snowflake-mcp
  • Implantação remota: http://<hostname>:<port>/snowflake-mcp

Claude Desktop

Adicione isso ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "url": "http://localhost:9000/snowflake-mcp"
    }
  }
}

Cursor

Adicione isso às suas configurações de MCP no Cursor (Configurações -> Configurações do Cursor -> MCP):

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "url": "http://localhost:9000/snowflake-mcp"
    }
  }
}

fast-agent

Adicione isso ao seu fastagent.config.yaml:

# MCP Servers
mcp:
    servers:
        mcp-server-snowflake:
            url: "http://localhost:9000/snowflake-mcp"

Notas:

  • Para implantações remotas, substitua localhost:9000 pelo nome do host e porta do seu servidor
  • Certifique-se de que seu firewall permita conexões na porta 9000 (ou na porta configurada)
  • Para implantações de produção, considere usar HTTPS e autenticação adequada

Serviços Cortex

Instâncias de Cortex Agent (na seção agent_services), Cortex Search (na seção search_services) e Cortex Analyst (na seção analyst_services) do arquivo de configuração serão servidas como ferramentas. Deixe essas seções em branco para omitir tais ferramentas.

Somente objetos Cortex Agent são suportados no servidor MCP. Ou seja, apenas objetos Cortex Agent pré-configurados no Snowflake podem ser usados como ferramentas. Consulte API de Execução do Cortex Agent para mais detalhes.

Certifique-se de que todos os serviços tenham nomes de contexto precisos para nome do serviço, banco de dados, schema, etc. Descrições ideais são altamente descritivas e mutuamente exclusivas.

O valor semantic_model em serviços de analyst deve ser uma visualização semântica totalmente qualificada OU um arquivo YAML semântico em um stage do Snowflake:

  • Para uma visualização semântica: MY_DATABASE.MY_SCHEMA.MY_SEMANTIC_VIEW
  • Para um arquivo YAML semântico: @MY_DATABASE.MY_SCHEMA.MY_STAGE/my_semantic_file.yaml (Observe o @.)

Gerenciamento de Objetos

O servidor MCP inclui dezenas de ferramentas com escopo restrito para cumprir o gerenciamento básico de operações. Recomenda-se usar o Snowsight diretamente para gerenciamento avançado de objetos. O servidor MCP atualmente suporta criar, remover, criar ou alterar, descrever e listar os seguintes tipos de objetos. Para habilitar essas ferramentas, defina object_manager como True no arquivo de configuração em other_services.

- Database
- Schema
- Table
- View
- Warehouse
- Compute Pool
- Role
- Stage
- User
- Image Repository

Observe que essas ferramentas também são regidas por permissões capturadas no arquivo de configuração em sql_statement_permissions. As ferramentas de gerenciamento de objetos para criar e criar ou alterar objetos são regidas pela permissão Create. A remoção de objetos é regida pela permissão Drop.

É provável que mais ações e objetos sejam incluídos em versões futuras.

Execução de SQL

A ferramenta SQL geral fornecerá uma maneira de executar instruções SQL genéricas geradas pelo cliente MCP. Os usuários têm controle total sobre os tipos de instruções SQL aprovadas no arquivo de configuração.

Listados no arquivo de configuração em sql_statement_permissions estão os tipos de expressão sqlglot. Aqueles marcados como False serão interrompidos antes da execução. Aqueles marcados como True serão executados (ou solicitarão a execução ao usuário com base nas configurações do cliente MCP).

Para habilitar a ferramenta de execução de SQL, defina query_manager como True no arquivo de configuração em other_services. Para permitir que todas as expressões SQL passem pela validação adicional, defina All como True.

Nem todos os comandos SQL do Snowflake são mapeados no sqlglot e você pode descobrir que alguns comandos obscuros ainda não foram capturados no arquivo de configuração. Definir Unknown como True permitirá que esses comandos não capturados passem pela validação adicional. Você também pode adicionar novos tipos de expressão diretamente para honrar tipos específicos.

Abaixo estão alguns exemplos de tipos de expressão sqlglot com exemplos de comandos SQL do Snowflake:

Tipo de Expressão SQLGlotComando SQL
AlterALTER TABLE my_table ADD COLUMN new_column VARCHAR(50);
CommandCALL my_procedure('param1_value', 123);
GRANT ROLE analyst TO USER user1;
SHOW TABLES IN SCHEMA my_database.my_schema;
CommentCOMMENT ON TABLE my_table IS 'This table stores customer data.';
CommitCOMMIT;
CreateCREATE TABLE my_table ( id INT, name VARCHAR(255), email VARCHAR(255) );
CREATE OR ALTER VIEW my_schema.my_new_view AS SELECT id, name, created_at FROM my_schema.my_table WHERE created_at >= '2023-01-01';
DeleteDELETE FROM my_table WHERE id = 101;
DescribeDESCRIBE TABLE my_table;
DropDROP TABLE my_table;
ErrorCOPY INTO my_table FROM @my_stage/data/customers.csv FILE_FORMAT = (TYPE = CSV SKIP_HEADER = 1 FIELD_DELIMITER = ',');
REVOKE ROLE analyst FROM USER user1;
UNDROP TABLE my_table;
InsertINSERT INTO my_table (id, name, email) VALUES (102, 'Jane Doe', 'jane.doe@example.com');
MergeMERGE INTO my_table AS target USING (SELECT 103 AS id, 'John Smith' AS name, 'john.smith@example.com' AS email) AS source ON target.id = source.id WHEN MATCHED THEN UPDATE SET target.name = source.name, target.email = source.email WHEN NOT MATCHED THEN INSERT (id, name, email) VALUES (source.id, source.name, source.email);
RollbackROLLBACK;
SelectSELECT id, name FROM my_table WHERE id < 200 ORDER BY name;
TransactionBEGIN;
TruncateTableTRUNCATE TABLE my_table;
UpdateUPDATE my_table SET email = 'new.email@example.com' WHERE name = 'Jane Doe';
UseUSE DATABASE my_database;

Consulta de Semantic Views

Várias ferramentas suportam a descoberta e consulta de Snowflake Semantic Views e seus componentes. As Semantic Views podem ser listadas e descritas. Além disso, você pode listar suas métricas e dimensões. Por fim, você pode consultar Semantic Views diretamente.

Para habilitar essas ferramentas, defina semantic_manager como True no arquivo de configuração em other_services.

Solução de Problemas

Executando o MCP Inspector

O MCP Inspector é uma ferramenta de depuração poderosa que fornece uma interface web para interagir diretamente com seu servidor MCP. É essencial para solucionar problemas de configuração, testar ferramentas e validar sua configuração.

Uso Básico do Inspector

Inicie o inspector com a configuração do seu servidor MCP:

npx @modelcontextprotocol/inspector uvx snowflake-labs-mcp --service-config-file <path_to_file>/tools_config.yaml --connection-name "default"

O que o Inspector Mostra para Você

Uma vez iniciado, o inspector abrirá uma interface web onde você pode:

  1. Visualizar Ferramentas Disponíveis: Ver todas as ferramentas MCP carregadas do seu arquivo de configuração
  2. Testar Execução de Ferramentas: Chamar ferramentas diretamente com parâmetros personalizados para verificar se funcionam
  3. Inspecionar Recursos: Visualizar quaisquer recursos expostos pelo servidor
  4. Depurar Problemas de Conexão: Ver mensagens de erro detalhadas se a conexão falhar
  5. Validar Configuração: Garantir que suas configurações de serviço estejam carregadas corretamente

Cenários Comuns de Solução de Problemas

Problemas com o Arquivo de Configuração:

  • Se as ferramentas não aparecerem, verifique sua sintaxe tools_config.yaml
  • Verifique se os nomes dos serviços e as referências de banco de dados/esquema estão corretos
  • Garanta que other_services estejam definidos como True para os grupos de ferramentas desejados

Problemas de Conexão:

  • Verifique se seus parâmetros de conexão do Snowflake estão corretos
  • Verifique se sua função tem as permissões necessárias para os serviços configurados
  • Para autenticação por par de chaves, garanta que sua chave privada esteja formatada corretamente

Erros de Execução de Ferramentas:

  • Use o inspector para testar ferramentas individuais com parâmetros conhecidos como válidos
  • Verifique os logs do servidor para mensagens de erro detalhadas
  • Verifique se os objetos subjacentes do Snowflake (bancos de dados, esquemas, serviços) existem

Métodos Alternativos de Depuração

Usando Logs MCP do Cursor:

  • Abra o painel de Saída no Cursor
  • Selecione "Cursor MCP" no menu suspenso
  • Visualize logs em tempo real enquanto interage com o servidor MCP

Depuração pela Linha de Comando:

Habilite o log de depuração com --verbose ou defina SNOWFLAKE_MCP_VERBOSE=true:

uvx snowflake-labs-mcp --service-config-file <path_to_file>/tools_config.yaml --connection-name "default" --verbose

Perguntas Frequentes

Como me conecto ao Snowflake?

Estou recebendo um erro/aviso de limite de ferramentas.

  • Embora o suporte dos LLMs para mais ferramentas provavelmente cresça, você pode ocultar grupos de ferramentas definindo-os como False no arquivo de configuração. Apenas os serviços Cortex listados serão transformados em ferramentas também.

Posso usar um Token de Acesso Programático (PAT) em vez de uma senha?

  • Sim. Passe-o para a flag da CLI --password ou defina-o como variável de ambiente SNOWFLAKE_PASSWORD.

Como posso experimentar isso?

  • O servidor MCP é destinado a ser usado como uma parte do ecossistema MCP. Pense nele como uma coleção de ferramentas. Você precisará de um Cliente MCP para atuar como orquestrador. Consulte a Introdução ao MCP para mais informações.

Onde isso é implantado? Está no Snowpark Container Services?

  • Todas as ferramentas neste servidor MCP são serviços gerenciados, acessíveis via API REST. Nenhuma implantação de serviço remoto separada é necessária. Em vez disso, a versão atual do servidor é destinada a ser iniciada pelo cliente MCP, como Claude Desktop, Cursor, fast-agent, etc. Ao configurar esses clientes MCP com o servidor, o aplicativo iniciará o serviço do servidor para você. Versões futuras do servidor MCP podem ser implantadas como um serviço remoto no futuro.

Estou recebendo erros de permissão nas minhas chamadas de ferramentas.

  • Se estiver usando Tokens de Acesso Programático, observe que eles não avaliam funções secundárias. Ao criá-los, selecione uma única função que tenha acesso a todos os serviços e seus objetos subjacentes OU selecione qualquer função. Um novo PAT precisará ser criado para alterar essa propriedade.

Quantos Cortex Search ou Cortex Analysts posso adicionar?

  • Você pode adicionar múltiplas instâncias de ambos os serviços. O Cliente MCP determinará qual(is) usar com base no prompt do usuário.

Socorro! Estou recebendo um SSLError?

  • Se o nome da sua conta contiver sublinhados, tente usar a versão com hífens da URL.
    • Identificador de conta com sublinhados: acme-marketing_test_account
    • Identificador de conta com hífens: acme-marketing-test-account

Como executo o servidor MCP em um contêiner para múltiplos usuários?

  • Implante usando Docker ou Docker Compose conforme mostrado na seção Implantação em Contêiner. O servidor em contêiner roda em HTTP e pode lidar com múltiplas conexões MCP client simultâneas. Configure suas variáveis de ambiente para autenticação e monte seu arquivo de configuração como um volume somente leitura.

Por que meus serviços Cortex não estão aparecendo como ferramentas?

  • Verifique se a sintaxe do seu arquivo de configuração está correta (use o MCP Inspector para validar)
  • Garanta que os nomes dos serviços, nomes dos bancos de dados e nomes dos esquemas correspondam exatamente ao que existe no Snowflake
  • Verifique se sua função tem acesso aos bancos de dados e esquemas especificados
  • Confirme se os serviços Cortex realmente existem nos locais especificados

Posso usar diferentes métodos de autenticação para diferentes ambientes?

  • Sim. Você pode definir variáveis de ambiente de forma diferente para cada implantação, usar diferentes nomes de conexão no seu arquivo connections.toml, ou passar diferentes argumentos de CLI. O servidor suporta todos os métodos de autenticação do Snowflake Python Connector, incluindo nome de usuário/senha, pares de chaves, OAuth e SSO.

Como limito quais instruções SQL podem ser executadas?

  • Use a seção sql_statement_permissions no seu arquivo de configuração. Defina tipos específicos de instruções como True (permitir) ou False (negar). Para máxima segurança, habilite apenas os tipos de instruções que você realmente precisa. Defina Unknown como False para bloquear tipos de instruções não reconhecidos.

O servidor MCP está lento para iniciar. Isso é normal?

  • A inicialização inicial pode levar alguns segundos enquanto o servidor se conecta ao Snowflake e valida sua configuração. Chamadas de ferramentas subsequentes devem ser muito mais rápidas. Se a inicialização levar mais de 30 segundos, verifique sua conexão de rede com o Snowflake e valide suas credenciais de autenticação.