Snowflake Cortex AI

Servidor Snowflake Cortex AI Model Context Protocol (MCP)

Este servidor MCP da Snowflake fornece ferramentas para os recursos do Snowflake Cortex AI, trazendo essas capacidades para o ecossistema MCP. Quando conectado a um Cliente MCP (ex.: Claude for Desktop, fast-agent, Agentic Orchestration Framework), os usuários podem aproveitar esses recursos do Cortex AI.

O servidor MCP atualmente suporta as seguintes capacidades do Cortex AI:

• Cortex Search: Consulte dados não estruturados no Snowflake, como comumente usado em aplicações de Retrieval Augmented Generation (RAG).
• Cortex Analyst: Consulte dados estruturados no Snowflake por meio de modelagem semântica rica.
• Cortex Complete: Chat-completion simples com parâmetros opcionais usando vários LLMs disponíveis.
• Cortex Agent: (Em breve) Orquestrador agêntico para recuperação de dados estruturados e não estruturados.

Primeiros Passos

Configuração do Serviço

Um arquivo de configuração simples é usado para criar ferramentas para os diversos recursos do Cortex AI. Um exemplo pode ser visto em services/service_config.yaml e um modelo está abaixo. Muitos serviços de Cortex Search e Cortex Analyst podem ser adicionados. Descrições ideais são altamente descritivas e mutuamente exclusivas. O caminho para este arquivo de configuração será passado ao servidor e o conteúdo será usado para criar ferramentas do servidor MCP na inicialização.

cortex_complete: # Set default model if one is not specified by user in Cortex Copmlete tool
  default_model: "snowflake-llama-3.3-70b"
search_services: # List all Cortex Search services
  - service_name: "<service_name>"
    description: > # Should start with "Search service that ..."
      "<Search services that ...>"
    database_name: "<database_name>"
    schema_name: "<schema_name>"
  - service_name: "<service_name>"
    description: > # Should start with "Search service that ..."
      "<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: > # Should start with "Analyst service that ..."
      "<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: > # Should start with "Analyst service that ..."
      "<Analyst service that ...>"

Identificador de Conta Snowflake

Um nome de usuário e identificador de conta Snowflake serão necessários para conectar. No Snowsight, selecione seu nome de usuário e Conecte uma ferramenta ao Snowflake para obter seu identificador de conta Snowflake. Isso será passado ao servidor na inicialização.

Autenticação com Token de Acesso Programático

O servidor MCP usa Snowflake Programmatic Access Token (PAT) para autenticação. Siga as instruções para gerar um novo PAT para um determinado usuário. Certifique-se de copiar o token — ele será passado ao servidor na inicialização.

[!IMPORTANT] PATs não usam funções secundárias. Selecione uma função específica que tenha acesso a todos os serviços desejados e seus objetos relacionados OU selecione Qualquer uma das minhas funções.

Uso com Clientes MCP

O servidor MCP é agnóstico de cliente e funcionará com a maioria dos Clientes MCP que suportam funcionalidades básicas para ferramentas MCP e (opcionalmente) recursos. Abaixo estão alguns exemplos.

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, ela está localizada 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 os valores das variáveis de ambiente SNOWFLAKE_PAT, SNOWFLAKE_ACCOUNT e SNOWFLAKE_USER.

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Snowflake-Labs/mcp",
        "mcp-server-snowflake",
        "--service-config-file",
        "<path to file>/service_config.yaml"
      ]
      "env": {
        "SNOWFLAKE_PAT": "<programmatic_access_token>",
        "SNOWFLAKE_ACCOUNT": "<account-identifier>",
        "SNOWFLAKE_USER": "<username>"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "mcp-server-snowflake": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Snowflake-Labs/mcp",
        "mcp-server-snowflake",
        "--service-config-file",
        "<path to file>/service_config.yaml",
        "--account-identifier",
        "<account-identifier>",
        "--username",
        "<username>",
        "--pat",
        "<programmatic_access_token>"
      ]
    }
  }
}

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 um caminho atualizado para o arquivo de configuração.

# MCP Servers
mcp:
    servers:
        mcp-server-snowflake:
            command: "uvx"
            args: ["--from", "git+https://github.com/Snowflake-Labs/mcp", "mcp-server-snowflake", "--service-config-file", "<path to file>/service_config.yaml"]

Atualize a seção do servidor mcp fastagent.secrets.yaml com as variáveis de ambiente.

mcp:
    servers:
        mcp-server-snowflake:
            env:
                SNOWFLAKE_PAT: <add-PAT>
                SNOWFLAKE_ACCOUNT: <add-snowflake-account-identifier>
                SNOWFLAKE_USER: <add-snowflake-username>

Solução de Problemas

Executando o MCP Inspector

O MCP Inspector é sugerido para solucionar problemas do servidor MCP. Execute o comando abaixo para iniciar o inspector. Certifique-se de que os valores para o arquivo de configuração do serviço, SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER e SNOWFLAKE_PAT estejam definidos adequadamente.

npx @modelcontextprotocol/inspector uvx --from "git+https://github.com/Snowflake-Labs/mcp" mcp-server-snowflake --service-config-file "<path_to_file>/service_config.yaml" --account-identifier $SNOWFLAKE_ACCOUNT --username $SNOWFLAKE_USER --pat $SNOWFLAKE_PAT

Perguntas Frequentes

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. Veja 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 remota de serviço 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 ferramenta.

• Tokens de Acesso Programático 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.

Relatórios de Bugs, Feedback ou Outras Perguntas

Por favor, adicione problemas ao repositório do GitHub.