Snowflake Cortex AI

Un servidor para Snowflake que proporciona herramientas para sus funciones de Cortex AI, incluyendo Search, Analyst y Complete.

Documentación

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

[!CAUTION] Este proyecto está obsoleto y ya no se mantiene. Por favor, migre al Snowflake MCP Server oficial. El servidor oficial se desarrolla activamente, cuenta con soporte completo de Snowflake y continúa añadiendo nuevas funciones.

Este servidor MCP comunitario proporcionaba anteriormente herramientas para Snowflake Cortex AI, gestión de objetos y orquestación SQL. Ya no tiene soporte. Para todos los casos de uso nuevos y existentes, utilice el Snowflake MCP Server oficial en su lugar.


Documentación heredada (solo para referencia)

El servidor MCP admitía las siguientes capacidades:

  • Cortex Search: Consultar datos no estructurados en Snowflake, como se usa comúnmente en aplicaciones de Generación Aumentada por Recuperación (RAG).
  • Cortex Analyst: Consultar datos estructurados en Snowflake mediante un modelado semántico enriquecido.
  • Cortex Agent: Orquestador agéntico para la recuperación de datos estructurados y no estructurados.
  • Gestión de objetos: Realizar operaciones básicas sobre los objetos más comunes de Snowflake, como creación, eliminación, actualización y más.
  • Ejecución de SQL: Ejecutar SQL generado por LLM gestionado por permisos configurados por el usuario.
  • Consulta de vistas semánticas: Descubrir y consultar vistas semánticas de Snowflake.

Primeros pasos

Configuración del servicio

Se utiliza un archivo de configuración simple para controlar todas las herramientas. Puede ver un ejemplo en services/configuration.yaml y a continuación se muestra una plantilla. La ruta a este archivo de configuración se pasará al servidor y el contenido se utilizará para crear las herramientas del servidor MCP al inicio.

Servicios Cortex

Se pueden agregar muchos servicios de Cortex Agent, Search y Analyst. Las descripciones ideales son altamente descriptivas y mutuamente excluyentes. Solo los servicios Cortex explícitamente listados estarán disponibles como herramientas en el cliente MCP.

Otros servicios

Otros servicios incluyen herramientas para gestión de objetos, ejecución de consultas y uso de vistas semánticas. Estos grupos de herramientas se pueden habilitar configurándolos como True en la sección other_services del archivo de configuración.

Permisos de sentencias SQL

La sección sql_statement_permissions garantiza que solo se ejecuten sentencias aprobadas en cualquier herramienta con acceso para modificar objetos de Snowflake. La lista contiene tipos de expresiones SQL. Las marcadas con True están permitidas, mientras que las marcadas con False no lo están. Consulte Ejecución de SQL para ver ejemplos de cada tipo de expresión.

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

[!NOTA] Las versiones anteriores del archivo de configuración admitían especificar valores explícitos para columnas y límite para cada servicio de Cortex Search. En cambio, ahora son exclusivamente dinámicos según la solicitud del usuario. Si no se especifican, se devolverán las search_columns predeterminadas del servicio de búsqueda con un límite de 10.

Conexión a Snowflake

El servidor MCP utiliza el Snowflake Python Connector para todos los métodos de autenticación y conexión. Consulte la documentación oficial de Snowflake para conocer las opciones de autenticación completas y las mejores prácticas.

El servidor MCP respeta los permisos RBAC asignados al rol especificado (según se pasa en los parámetros de conexión) o al rol predeterminado del usuario (si no se pasa ningún rol para conectarse).

Los parámetros de conexión se pueden pasar como argumentos de CLI y/o variables de entorno. El servidor admite todos los métodos de autenticación disponibles en el Snowflake Python Connector, incluidos:

  • Autenticación de usuario/contraseña
  • Autenticación de par de claves
  • Autenticación OAuth
  • Inicio de sesión único (SSO)
  • Autenticación multifactor (MFA)

Parámetros de conexión

Los parámetros de conexión se pueden pasar como argumentos de CLI y/o variables de entorno:

ParámetroArgumentos de CLIVariable de entornoDescripción
Account--accountSNOWFLAKE_ACCOUNTIdentificador de cuenta (p. ej., xy12345.us-east-1)
Host--hostSNOWFLAKE_HOSTURL del host de Snowflake
User--user, --usernameSNOWFLAKE_USERNombre de usuario para autenticación
Password--passwordSNOWFLAKE_PASSWORDContraseña o token de acceso programático
Role--roleSNOWFLAKE_ROLERol a utilizar para la conexión
Warehouse--warehouseSNOWFLAKE_WAREHOUSEAlmacén a utilizar para consultas
Passcode in Password--passcode-in-password-Si el código de acceso está incrustado en la contraseña
Passcode--passcodeSNOWFLAKE_PASSCODECódigo de acceso MFA para autenticación
Private Key--private-keySNOWFLAKE_PRIVATE_KEYClave privada para autenticación de par de claves
Private Key File--private-key-fileSNOWFLAKE_PRIVATE_KEY_FILERuta al archivo de clave privada
Private Key Password--private-key-file-pwdSNOWFLAKE_PRIVATE_KEY_FILE_PWDContraseña para clave privada cifrada
Authenticator--authenticator-Tipo de autenticación (predeterminado: snowflake)
Connection Name--connection-name-Nombre de la conexión del archivo connections.toml (o config.toml)

[!ADVERTENCIA] Aviso de obsolescencia: Los argumentos de CLI --account-identifier y --pat, así como la variable de entorno SNOWFLAKE_PAT, están obsoletos y se eliminarán en una versión futura. Utilice --account y --password (o SNOWFLAKE_ACCOUNT y SNOWFLAKE_PASSWORD) en su lugar.

Configuración de transporte

El servidor MCP admite múltiples mecanismos de transporte. Para obtener información detallada sobre los transportes MCP, consulte Protocolos de transporte de FastMCP.

TransporteDescripciónCaso de uso
stdioEntrada/salida estándar (predeterminado)Desarrollo local, integración con clientes MCP
sse (heredado)Server-Sent EventsAplicaciones de streaming
streamable-httpTransporte HTTP transmisibleImplementaciones en contenedores, 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

Personalizaciones de transporte

Personalizaciones del servidor disponibles para los transportes sse y streamable-http:

ParámetroArgumento de CLIVariable de entornoPredeterminado
Host--server-hostSNOWFLAKE_MCP_HOST"0.0.0.0"
Port--portSNOWFLAKE_MCP_PORT9000
Endpoint--endpointSNOWFLAKE_MCP_ENDPOINT/mcp
Debug Logging--verboseSNOWFLAKE_MCP_VERBOSEfalse

Ejemplo:

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

Uso con clientes MCP

El servidor MCP es agnóstico respecto al cliente y funcionará con la mayoría de los clientes MCP que admitan funcionalidad básica para herramientas MCP y (opcionalmente) recursos. A continuación se muestran ejemplos para instalación local. Para conectarse a implementaciones en contenedores, consulte Conexión de clientes MCP a contenedores.

Claude Desktop

Para integrar este servidor con Claude Desktop como cliente MCP, agregue lo siguiente a la configuración del servidor de su aplicación. De forma predeterminada, se encuentra en:

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

Establezca la ruta al archivo de configuración del servicio y configure su método de conexión:

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

Cursor

Registre el servidor MCP en Cursor abriendo Cursor y navegando a Configuración -> Configuración de Cursor -> MCP. Agregue lo siguiente:

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

Agregue el servidor MCP como contexto en el chat.

Para solucionar problemas del servidor de Cursor, consulte los registros abriendo el panel de Salida y seleccionando Cursor MCP en el menú desplegable.

fast-agent

Actualice la sección del servidor mcp fastagent.config.yaml con la ruta del archivo de configuración y el nombre de la conexión:

# 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 requisitos previos, configuración del entorno, guía paso a paso e instrucciones, consulte este blog.

Codex

Registre el servidor MCP en codex agregando lo siguiente 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"
]

Después de editar, el mcp de snowflake debería aparecer en la salida de codex mcp list ejecutado desde la terminal.

Implementación en contenedores

Implemente el servidor MCP como contenedor para acceso remoto o entornos de producción. Esta guía proporciona instrucciones paso a paso para implementaciones con Docker y Docker Compose.

Implementación con Docker

Siga estos pasos para implementar el servidor MCP usando Docker:

Paso 1: Preparar el archivo de configuración

Cree un directorio para la configuración de MCP y copie la plantilla:

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

Paso 2: Configurar los servicios

Edite el archivo de configuración para que coincida con su entorno:

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

Paso 3: Crear la imagen del contenedor

Cree la imagen de Docker a partir del Dockerfile proporcionado:

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

Paso 4: Establecer variables de entorno

Configure sus parámetros de conexión a Snowflake. Elija uno de los siguientes métodos de autenticación:

Autenticación de usuario/contraseña:

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

Autenticación de par de claves:

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>

Paso 5: Ejecutar el contenedor

Inicie el contenedor con su configuración y variables de entorno:

Para autenticación de usuario/contraseña:

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 autenticación de par de claves:

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

Paso 6: Verificar la implementación

Verifique que el contenedor esté en ejecución y sea accesible:

# 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

Implementación con Docker Compose

Siga estos pasos para una implementación simplificada usando Docker Compose:

Paso 1: Preparar el archivo de configuración

Cree el directorio de configuración y copie la plantilla:

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

Paso 2: Configurar los servicios

Edite el archivo de configuración para que coincida con su entorno:

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

Paso 3: Establecer variables de entorno

Configure sus parámetros de conexión a 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>

Paso 4: Iniciar los servicios

Lance el contenedor usando Docker Compose:

docker-compose up -d

Paso 5: Verificar la implementación

Verifique que los servicios estén en ejecución:

# Check service status
docker-compose ps

# View logs
docker-compose logs

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

Conexión de clientes MCP a contenedores

Una vez que su servidor MCP esté en ejecución en un contenedor, puede conectar varios clientes MCP a él. La configuración de conexión es la misma para todos los clientes; solo difiere el formato de configuración.

Formato de URL de conexión:

  • Implementación local: http://localhost:9000/snowflake-mcp
  • Implementación remota: http://<hostname>:<port>/snowflake-mcp

Claude Desktop

Agregue esto a su claude_desktop_config.json:

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

Cursor

Agregue esto a su configuración de MCP en Cursor (Configuración -> Configuración de Cursor -> MCP):

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

fast-agent

Agregue esto a su fastagent.config.yaml:

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

Notas:

  • Para implementaciones remotas, reemplace localhost:9000 con el nombre de host y el puerto de su servidor
  • Asegúrese de que su firewall permita conexiones en el puerto 9000 (o el puerto configurado)
  • Para implementaciones de producción, considere usar HTTPS y autenticación adecuada

Servicios Cortex

Las instancias de Cortex Agent (en la sección agent_services), Cortex Search (en la sección search_services) y Cortex Analyst (en la sección analyst_services) del archivo de configuración se servirán como herramientas. Deje estas secciones en blanco para omitir dichas herramientas.

Solo se admiten objetos de Cortex Agent en el servidor MCP. Es decir, solo los objetos de Cortex Agent preconfigurados en Snowflake se pueden utilizar como herramientas. Consulte API de ejecución de Cortex Agent para obtener más detalles.

Asegúrese de que todos los servicios tengan nombres de contexto precisos para el nombre del servicio, base de datos, esquema, etc. Las descripciones ideales son altamente descriptivas y mutuamente excluyentes.

El valor semantic_model en los servicios de analyst debe ser una vista semántica totalmente calificada O un archivo YAML semántico en un stage de Snowflake:

  • Para una vista semántica: MY_DATABASE.MY_SCHEMA.MY_SEMANTIC_VIEW
  • Para un archivo YAML semántico: @MY_DATABASE.MY_SCHEMA.MY_STAGE/my_semantic_file.yaml (Tenga en cuenta el @.)

Gestión de objetos

El servidor MCP incluye docenas de herramientas con un alcance limitado para cumplir con la gestión básica de operaciones. Se recomienda usar Snowsight directamente para la gestión avanzada de objetos. El servidor MCP actualmente soporta crear, eliminar, crear o modificar, describir y listar los siguientes tipos de objetos. Para habilitar estas herramientas, establezca object_manager en True en el archivo de configuración bajo other_services.

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

Tenga en cuenta que estas herramientas también están sujetas a los permisos capturados en el archivo de configuración bajo sql_statement_permissions. Las herramientas de gestión de objetos para crear y crear o modificar objetos están sujetas al permiso Create. La eliminación de objetos está sujeta al permiso Drop.

Es probable que se incluyan más acciones y objetos en futuras versiones.

Ejecución de SQL

La herramienta SQL general proporcionará una forma de ejecutar sentencias SQL genéricas generadas por el cliente MCP. Los usuarios tienen control total sobre los tipos de sentencias SQL que se aprueban en el archivo de configuración.

En el archivo de configuración, bajo sql_statement_permissions, se enumeran los tipos de expresiones sqlglot. Aquellos marcados como False se detendrán antes de la ejecución. Los marcados con True se ejecutarán (o solicitarán al usuario la ejecución según la configuración del cliente MCP).

Para habilitar la herramienta de ejecución de SQL, establezca query_manager en True en el archivo de configuración bajo other_services. Para permitir que todas las expresiones SQL pasen la validación adicional, establezca All en True.

No todos los comandos SQL de Snowflake están mapeados en sqlglot y es posible que algunos comandos poco comunes aún no estén capturados en el archivo de configuración. Establecer Unknown en True permitirá que estos comandos no capturados pasen la validación adicional. También puede agregar nuevos tipos de expresiones directamente para honrar algunos específicos.

A continuación se muestran algunos ejemplos de tipos de expresiones sqlglot con ejemplos de comandos SQL de Snowflake:

Tipo de Expresión 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 Vistas Semánticas

Varias herramientas soportan el descubrimiento y la consulta de Vistas Semánticas de Snowflake y sus componentes. Las Vistas Semánticas se pueden listar y describir. Además, puede listar sus métricas y dimensiones. Por último, puede consultar Vistas Semánticas directamente.

Para habilitar estas herramientas, establezca semantic_manager en True en el archivo de configuración bajo other_services.

Solución de Problemas

Ejecutar MCP Inspector

El MCP Inspector es una poderosa herramienta de depuración que proporciona una interfaz web para interactuar directamente con su servidor MCP. Es esencial para solucionar problemas de configuración, probar herramientas y validar su configuración.

Uso Básico del Inspector

Inicie el inspector con la configuración de su servidor MCP:

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

Lo que Muestra el Inspector

Una vez iniciado, el inspector abrirá una interfaz web donde podrá:

  1. Ver Herramientas Disponibles: Ver todas las herramientas MCP cargadas desde su archivo de configuración
  2. Probar la Ejecución de Herramientas: Llamar a las herramientas directamente con parámetros personalizados para verificar que funcionan
  3. Inspeccionar Recursos: Ver cualquier recurso expuesto por el servidor
  4. Depurar Problemas de Conexión: Ver mensajes de error detallados si la conexión falla
  5. Validar Configuración: Asegurarse de que las configuraciones de servicio estén cargadas correctamente

Escenarios Comunes de Solución de Problemas

Problemas con el Archivo de Configuración:

  • Si las herramientas no aparecen, verifique su sintaxis tools_config.yaml
  • Verifique que los nombres de servicio y las referencias de base de datos/esquema sean correctos
  • Asegúrese de que other_services estén establecidos en True para los grupos de herramientas que desee

Problemas de Conexión:

  • Verifique que sus parámetros de conexión a Snowflake sean correctos
  • Compruebe que su rol tenga los permisos necesarios para los servicios que ha configurado
  • Para la autenticación con par de claves, asegúrese de que su clave privada esté formateada correctamente

Errores de Ejecución de Herramientas:

  • Use el inspector para probar herramientas individuales con parámetros conocidos
  • Revise los registros del servidor para obtener mensajes de error detallados
  • Verifique que los objetos subyacentes de Snowflake (bases de datos, esquemas, servicios) existan

Métodos Alternativos de Depuración

Uso de Registros MCP de Cursor:

  • Abra el panel de Salida en Cursor
  • Seleccione "Cursor MCP" en el menú desplegable
  • Vea los registros en tiempo real mientras interactúa con el servidor MCP

Depuración desde Línea de Comandos:

Habilite el registro de depuración con --verbose o establezca SNOWFLAKE_MCP_VERBOSE=true:

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

Preguntas Frecuentes

¿Cómo me conecto a Snowflake?

Estoy recibiendo un error/advertencia de límite de herramientas.

  • Si bien el soporte de los LLM para más herramientas probablemente crecerá, puede ocultar grupos de herramientas estableciéndolos en False en el archivo de configuración. Solo los servicios Cortex listados se convertirán en herramientas también.

¿Puedo usar un Token de Acceso Programático (PAT) en lugar de una contraseña?

  • Sí. Páselo a la bandera de CLI --password o establézcalo como variable de entorno SNOWFLAKE_PASSWORD.

¿Cómo pruebo esto?

  • El servidor MCP está diseñado para usarse como una parte del ecosistema MCP. Piense en él como una colección de herramientas. Necesitará un Cliente MCP que actúe como orquestador. Consulte la Introducción a MCP para obtener más información.

¿Dónde se implementa esto? ¿Está en Snowpark Container Services?

  • Todas las herramientas en este servidor MCP son servicios gestionados, accesibles a través de la API REST. No es necesaria una implementación de servicio remoto separada. En cambio, la versión actual del servidor está diseñada para ser iniciada por el cliente MCP, como Claude Desktop, Cursor, fast-agent, etc. Al configurar estos clientes MCP con el servidor, la aplicación iniciará el servicio del servidor por usted. Las versiones futuras del servidor MCP pueden implementarse como un servicio remoto en el futuro.

Estoy recibiendo errores de permisos de mis llamadas a herramientas.

  • Si usa Tokens de Acceso Programático, tenga en cuenta que no evalúan roles secundarios. Al crearlos, seleccione un solo rol que tenga acceso a todos los servicios y sus objetos subyacentes O seleccione cualquier rol. Se necesitará crear un nuevo PAT para alterar esta propiedad.

¿Cuántos Cortex Search o Cortex Analysts puedo agregar?

  • Puede agregar múltiples instancias de ambos servicios. El Cliente MCP determinará cuál(es) usar según la solicitud del usuario.

¡Ayuda! ¿Estoy recibiendo un SSLError?

  • Si su nombre de cuenta contiene guiones bajos, intente usar la versión con guiones de la URL.
    • Identificador de cuenta con guiones bajos: acme-marketing_test_account
    • Identificador de cuenta con guiones: acme-marketing-test-account

¿Cómo ejecuto el servidor MCP en un contenedor para múltiples usuarios?

  • Implemente usando Docker o Docker Compose como se muestra en la sección Implementación en Contenedor. El servidor contenerizado se ejecuta en HTTP y puede manejar múltiples conexiones de clientes MCP concurrentes. Configure sus variables de entorno para la autenticación y monte su archivo de configuración como un volumen de solo lectura.

¿Por qué mis servicios Cortex no aparecen como herramientas?

  • Verifique que la sintaxis de su archivo de configuración sea correcta (use MCP Inspector para validar)
  • Asegúrese de que los nombres de servicio, nombres de base de datos y nombres de esquema coincidan exactamente con lo que existe en Snowflake
  • Compruebe que su rol tenga acceso a las bases de datos y esquemas especificados
  • Confirme que los servicios Cortex realmente existan en las ubicaciones especificadas

¿Puedo usar diferentes métodos de autenticación para diferentes entornos?

  • Sí. Puede establecer variables de entorno de manera diferente para cada implementación, usar diferentes nombres de conexión en su archivo connections.toml, o pasar diferentes argumentos de CLI. El servidor soporta todos los métodos de autenticación del Conector Python de Snowflake, incluidos nombre de usuario/contraseña, pares de claves, OAuth y SSO.

¿Cómo limito qué sentencias SQL se pueden ejecutar?

  • Use la sección sql_statement_permissions en su archivo de configuración. Establezca tipos de sentencias específicos en True (permitir) o False (denegar). Para máxima seguridad, solo habilite los tipos de sentencias que realmente necesite. Establezca Unknown en False para bloquear tipos de sentencias no reconocidos.

El servidor MCP tarda en iniciarse. ¿Es esto normal?

  • El inicio inicial puede tomar unos segundos mientras el servidor se conecta a Snowflake y valida su configuración. Las llamadas a herramientas posteriores deberían ser mucho más rápidas. Si el inicio tarda más de 30 segundos, verifique su conexión de red a Snowflake y valide sus credenciales de autenticación.