Servidor MCP gerenciado pelo Snowflake¶

Visão geral¶

Nota

Snowflake oferece suporte à revisão do protocolo de contexto do modelo 2025-06-18.

Protocolo de contexto do modelo (MCP), é um padrão de código aberto que permite que os agentes de AI interajam de forma segura com aplicativos comerciais e sistemas de dados externos, como bancos de dados e repositórios de conteúdo. o MCP permite que as empresas reduzam os desafios de integração e forneçam resultados rapidamente a partir de modelos. Desde seu lançamento, o MCP tornou-se fundamental para aplicativos de agente, fornecendo um mecanismo consistente e seguro para invocar ferramentas e recuperar dados.

O servidor MCP gerenciado pelo Snowflake permite que os agentes de AI recuperam com segurança os dados de contas Snowflake sem precisar implementar uma infraestrutura separada. Você pode configurar o servidor MCP para fornecer o Cortex Analyst, o Cortex Search e os Cortex Agents como ferramentas, junto com as ferramentas personalizadas e as execuções SQL na interface baseada em padrões. Os clientes MCP descobrem e invocam essas ferramentas, além de recuperar os dados necessários para o aplicativo. Com servidores MCP gerenciados no Snowflake, você pode criar aplicativos escaláveis de nível empresarial, mantendo controles de acesso e privacidade. O servidor MCP no Snowflake fornece:

Integração padronizada: interface unificada para descoberta e invocação de ferramentas, em conformidade com os padrões em rápida evolução.
Autenticação abrangente: serviço OAuth integrado do Snowflake para permitir a autenticação baseada em OAuth para integrações MCP.
Governança robusta: controle de acesso baseado em função (RBAC) para servidor MCP e ferramentas para gerenciar a descoberta e a invocação de ferramentas.

Para obter mais informações sobre o ciclo de vida do MCP, consulte Ciclo de vida. Para um exemplo de uma implementação do MCP, consulte o guia de início rápido Introdução ao servidor MCP gerenciado pelo Snowflake.

Recomendações de segurança para o servidor MCP¶

Importante

Quando você configurar nomes de host para conexões de servidor MCP, use hifens (-) em vez de sublinhados (_). Os servidores MCP apresentam problemas de conexão com nomes de host que têm sublinhados.

O uso de vários servidores MCP sem verificação das ferramentas e descrições pode levar a vulnerabilidades, como envenenamento ou sombreamento de ferramenta. A Snowflake recomenda verificar os servidores MCP de terceiros antes de usá-los. Isso inclui o servidor MCP de outro usuário ou conta Snowflake. Verifique todas as ferramentas oferecidas pelos servidores MCP de terceiros.

Recomendamos usar OAuth como método de autenticação. O uso de tokens codificados pode levar a vazamento de tokens.

Ao usar um token de acesso programático (PAT), configure-o para usar a função menos privilegiada permitida para trabalhar com o MCP. Isso ajuda a impedir o vazamento de um segredo com acesso a uma função altamente privilegiada.

Configure as permissões adequadas para o servidor MCP e as ferramentas seguindo o princípio de privilégio mínimo. O acesso ao servidor MCP não dá acesso às ferramentas. A permissão precisa ser concedida para cada ferramenta.

Criar uma objeto do servidor MCP¶

Crie um objeto especificando as ferramentas e outros metadados. Os clientes MCP que se conectam ao servidor, após a autenticação necessária, podem descobrir e invocar essas ferramentas.

Navegue até o banco de dados e esquema desejados para criar o servidor MCP.

Criar o servidor MCP:

CREATE [ OR REPLACE ] MCP SERVER [ IF NOT EXISTS ] <server_name>
  FROM SPECIFICATION $$
    tools:
      - name: "product-search"
        type: "CORTEX_SEARCH_SERVICE_QUERY"
        identifier: "database1.schema1.Cortex_Search_Service1"
        description: "cortex search service for all products"
        title: "Product Search"

      - name: "revenue-semantic-view"
        type: "CORTEX_ANALYST_MESSAGE"
        identifier: "database1.schema1.Semantic_View_1"
        description: "Semantic view for all revenue tables"
        title: "Semantic view for revenue"
  $$

Atualmente, o Snowflake oferece suporte aos seguintes tipos de ferramentas:

CORTEX_SEARCH_SERVICE_QUERY: ferramenta Cortex Search Service

CORTEX_ANALYST_MESSAGE: ferramenta Cortex Analyst

SYSTEM_EXECUTE_SQL: execução SQL

CORTEX_AGENT_RUN: ferramenta Cortex Agent

GENERIC: ferramenta para UDFs e procedimentos armazenados

Os exemplos a seguir mostram como configurar diferentes tipos de ferramentas:
Usando a ferramenta Analyst, seu cliente pode gerar SQL de texto em linguagem natural. Use o código a seguir para especificar a configuração da ferramenta.

Nota

O servidor MCP gerenciado pelo Snowflake oferece suporte apenas ao uso de exibições semânticas com o Cortex Analyst. Ele não oferece suporte a modelos semânticos.
tools:
  - name: "revenue-semantic-view"
    type: "CORTEX_ANALYST_MESSAGE"
    identifier: "database1.schema1.Semantic_View_1"
    description: "Semantic view for all revenue tables"
    title: "Semantic view for revenue"
Usando as solicitações da ferramenta de pesquisa, seu cliente pode realizar uma pesquisa não estruturada nos dados.
tools:
  - name: "product-search"
    type: "CORTEX_SEARCH_SERVICE_QUERY"
    identifier: "database1.schema1.Cortex_Search_Service1"
    description: "cortex search service for all products"
    title: "Product Search"
Para a ferramenta de execução SQL, seu cliente pode executar consultas SQL no Snowflake. Use o código a seguir para especificar a configuração da ferramenta.
tools:
  - title: "SQL Execution Tool"
    name: "sql_exec_tool"
    type: "SYSTEM_EXECUTE_SQL"
    description: "A tool to execute SQL queries against the connected Snowflake database."
Para a ferramenta Agent, seu cliente passa uma mensagem ao agente. O agente processa a solicitação e retorna uma resposta. Use o código a seguir para especificar a configuração da ferramenta.
tools:
  - title: "Agent V2"
    name: "agent_1"
    type: "CORTEX_AGENT_RUN"
    identifier: "db.schema.agent"
    description: "agent that gives the ability to..."
Para suas ferramentas personalizadas, é necessário fornecer a função definida pelo usuário (User-Defined Function, UDF) ou a assinatura do procedimento armazenado na configuração da ferramenta. A ferramenta personalizada permite que você invoque UDFs e procedimentos armazenados como ferramentas pelo servidor MCP.

Você precisa especificar o seguinte na configuração da ferramenta:

type: function para UDF, procedure para procedimento armazenado

Warehouse. Se você não especificar um warehouse, o warehouse padrão será usado.

Input schema: corresponde à assinatura da função

Use os seguintes exemplos para criar e configurar ferramentas personalizadas usando UDFs e procedimentos armazenados:

Os exemplos a seguir demonstram a criação de UDFs que podem ser usadas como ferramentas personalizadas:

-- create a simple udf
CREATE OR REPLACE FUNCTION MULTIPLY_BY_TEN(x FLOAT)
RETURNS FLOAT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
HANDLER = 'multiply_by_ten'
AS
$$
def multiply_by_ten(x: float) -> float:
  return x * 10
$$;

SHOW FUNCTIONS LIKE 'MULTIPLY_BY_TEN';

-- test return json/variant
CREATE OR REPLACE FUNCTION CALCULATE_PRODUCT_AND_SUM(x FLOAT, y FLOAT)
RETURNS VARIANT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
HANDLER = 'calculate_values'
AS
$$
import json

def calculate_values(x: float, y: float) -> dict:
  """
  Calculates the product and sum of two numbers and returns them in a dictionary.
  The dictionary is converted to a VARIANT (JSON) in the SQL return.
  """
  product = x * y
  sum_val = x + y

  return {
      "product": product,
      "sum": sum_val
  }
$$;

-- test return list/array
CREATE OR REPLACE FUNCTION GET_NUMBERS_IN_RANGE(x FLOAT, y FLOAT)
RETURNS ARRAY -- Use ARRAY to explicitly state a list is being returned
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
HANDLER = 'get_numbers'
AS
$$
def get_numbers(x: float, y: float) -> list:
  """
  Returns a list of integers between x (exclusive) and y (inclusive).
  Assumes x < y.
  """
  # Ensure x and y are treated as integers for range generation
  start = int(x) + 1
  end = int(y) + 1 # range() is exclusive on the stop value

  # Use a list comprehension to generate the numbers
  # The Python list will be converted to a Snowflake ARRAY.
  return list(range(start, end))
$$;

Os exemplos a seguir demonstram a criação de procedimentos armazenados que podem ser usados como ferramentas personalizadas:

-- create a simple stored procedure
CREATE OR REPLACE PROCEDURE MULTIPLY_BY_TEN_SP(x FLOAT)
RETURNS FLOAT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'multiply_by_ten'
AS
$$
# The handler logic is identical to the UDF for a scalar return
def multiply_by_ten(x: float) -> float:
      return x * 10
$$;

-- test return json/variant
CREATE OR REPLACE PROCEDURE CALCULATE_VALUES_SP(x FLOAT, y FLOAT)
RETURNS VARIANT
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'calculate_values'
AS
$$
# The handler logic is identical to the UDF for a VARIANT return
def calculate_values(x: float, y: float) -> dict:
      """
      Calculates the product and sum of two numbers and returns them in a dictionary.
      The dictionary is converted to a VARIANT (JSON) in the SQL return.
      """
      product = x * y
      sum_val = x + y

      return {
          "product": product,
          "sum": sum_val
      }
$$;

-- test return list/array
CREATE OR REPLACE PROCEDURE GET_NUMBERS_SP(x FLOAT, y FLOAT)
RETURNS ARRAY
LANGUAGE PYTHON
RUNTIME_VERSION = '3.8'
PACKAGES = ('snowflake-snowpark-python')
HANDLER = 'get_numbers'
AS
$$
def get_numbers(x: float, y: float) -> list:
      """
      Returns a list of integers between x (exclusive) and y (inclusive).
      The Python list will be converted to a Snowflake ARRAY.
      """
      # Ensure x and y are treated as integers for range generation
      start = int(x) + 1
      end = int(y) + 1 # range() is exclusive on the stop value

      # Use a list comprehension to generate the numbers
      return list(range(start, end))
$$;

Os exemplos a seguir demonstram a configuração de ferramentas personalizadas para UDFs e procedimentos armazenados:

CREATE MCP SERVER my_mcp_server
  FROM SPECIFICATION $$
    tools:
      - title: "Custom Tool 1"
        identifier: "EXAMPLE_DATABASE.AGENTS.MULTIPLY_BY_TEN"
        name: "multiply_by_ten"
        type: "GENERIC"
        description: "Multiplied input value by ten and returns the result."
        config:
          type: "function"
          warehouse: "COMPUTE_SERVICE_WAREHOUSE"
          input_schema:
            type: "object"
            properties:
              x:
                description: "A number to be multiplied by ten"
                type: "number"
      - title: "Custom Tool 2"
        identifier: "EXAMPLE_DATABASE.AGENTS.CALCULATE_PRODUCT_AND_SUM"
        name: "calculate_product_and_sum"
        type: "GENERIC"
        description: "Calculates the product and sum of two numbers and returns them in a JSON object."
        config:
          type: "function"
          warehouse: "COMPUTE_SERVICE_WAREHOUSE"
          input_schema:
            type: "object"
            properties:
              x:
                description: "First number"
                type: "number"
              y:
                description: "Second number"
                type: "number"
      - title: "Custom Tool 3"
        identifier: "EXAMPLE_DATABASE.AGENTS.GET_NUMBERS_IN_RANGE"
        name: "get_numbers_in_range"
        type: "GENERIC"
        description: "Returns a list of integers between two numbers."
        config:
          type: "function"
          warehouse: "COMPUTE_SERVICE_WAREHOUSE"
          input_schema:
            type: "object"
            properties:
              x:
                description: "Start number (exclusive)"
                type: "number"
              y:
                description: "End number (inclusive)"
                type: "number"
      - title: "Custom Tool 4"
        identifier: "EXAMPLE_DATABASE.AGENTS.MULTIPLY_BY_TEN_SP"
        name: "multiply_by_ten_sp"
        type: "GENERIC"
        description: "Multiplied input value by ten and returns the result."
        config:
          type: "procedure"
          warehouse: "COMPUTE_SERVICE_WAREHOUSE"
          input_schema:
            type: "object"
            properties:
              x:
                description: "A number to be multiplied by ten"
                type: "number"
      - title: "Custom Tool 5"
        identifier: "EXAMPLE_DATABASE.AGENTS.CALCULATE_PRODUCT_AND_SUM_SP"
        name: "calculate_product_and_sum_sp"
        type: "GENERIC"
        description: "Calculates the product and sum of two numbers and returns them in a JSON object."
        config:
          type: "procedure"
          warehouse: "COMPUTE_SERVICE_WAREHOUSE"
          input_schema:
            type: "object"
            properties:
              x:
                description: "First number"
                type: "number"
              y:
                description: "Second number"
                type: "number"
      - title: "Custom Tool 6"
        identifier: "EXAMPLE_DATABASE.AGENTS.GET_NUMBERS_IN_RANGE_SP"
        name: "get_numbers_in_range_sp"
        type: "GENERIC"
        description: "Returns a list of integers between two numbers."
        config:
          type: "procedure"
          warehouse: "COMPUTE_SERVICE_WAREHOUSE"
          input_schema:
            type: "object"
            properties:
              x:
                description: "Start number (exclusive)"
                type: "number"
              y:
                description: "End number (inclusive)"
                type: "number"
  $$;

Para mostrar servidores MCP, use os seguintes comandos:

SHOW MCP SERVERS IN DATABASE <database_name>;
SHOW MCP SERVERS IN SCHEMA <schema_name>;
SHOW MCP SERVERS IN ACCOUNT;

O seguinte exemplo mostra a saída do comando:

|               created_on               |       name        | database_name | schema_name |    owner     |           comment            |
------------------------------------------+-------------------+---------------+-------------+--------------+------------------------------
| Fri, 23 Jun 1967 07:00:00.123000 +0000 | TEST_MCP_SERVER   | TEST_DATABASE | TEST_SCHEMA | ACCOUNTADMIN | [NULL]                       |
| Fri, 23 Jun 1967 07:00:00.123000 +0000 | TEST_MCP_SERVER_2 | TEST_DATABASE | TEST_SCHEMA | ACCOUNTADMIN | Test MCP server with comment |

Para descrever um servidor MCP, use o seguinte comando:

DESCRIBE MCP SERVER <server_name>;

O seguinte exemplo mostra a saída do comando:

|      name       | database_name | schema_name |    owner     | comment |     server_spec        |               created_on               |
------------------------------------------------------------------------------------------------------+-------------------------------------
| TEST_MCP_SERVER | TEST_DATABASE | TEST_SCHEMA | ACCOUNTADMIN | [NULL]  | {"version":1,"tools":[{"name":"product-search","identifier":"db.schema.search_service","type":"CORTEX_SEARCH_SERVICE_QUERY"}]} | Fri, 23 Jun 1967 07:00:00.123000 +0000 |

Para descartar um servidor MCP, use o seguinte comando:
```
DROP MCP SERVER <server_name>;
```

Controle de acesso¶

Você pode usar os privilégios a seguir para gerenciar o acesso ao servidor MCP e as ferramentas subjacentes.


Privilégio	Objeto	Descrição
CREATE	MCP SERVER	Necessário para criar o servidor MCP
OWNERSHIP	MCP SERVER	Necessário para atualizar a configuração do objeto
MODIFY	MCP SERVER	Fornece atualizar, descartar, descrever, mostrar e usar (`tools/list` e `tools/call`) na configuração do objeto
USAGE	MCP SERVER	Necessário para conectar-se ao servidor MCP e ferramentas de descoberta
USAGE	Cortex Search Service	Necessário para invocar a ferramenta Cortex Search no servidor MCP
SELECT	Exibição semântica	Necessário para invocar a ferramenta Cortex Analyst no servidor MCP
USAGE	Cortex Agent	Necessário para invocar o Cortex Agent como ferramenta no servidor MCP
USAGE	Função definida pelo usuário (UDF) ou procedimento armazenado	Necessário para invocar a UDF ou o procedimento armazenado como ferramenta no servidor MCP

Configurar a autenticação OAuth¶

Configure a autenticação no cliente MCP. O servidor MCP gerenciado pelo Snowflake oferece suporte ao OAuth 2.0, alinhado com a recomendação de autorização no protocolo MCP. O servidor MCP gerenciado pelo Snowflake não oferece suporte ao registro dinâmico de clientes.

Primeiro, crie a integração de segurança. Para mais informações sobre esse comando, consulte CREATE SECURITY INTEGRATION (Snowflake OAuth).

CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS] <integration_name>
  TYPE = OAUTH
  OAUTH_CLIENT = CUSTOM
  ENABLED = TRUE
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
  OAUTH_REDIRECT_URI = '<redirect_URI>'

Em seguida, chame a função de sistema para recuperar seu ID de cliente e chaves para configuração do cliente. O nome da integração diferencia maiúsculas de minúsculas e deve estar em maiúsculas.
```
SELECT SYSTEM$SHOW_OAUTH_CLIENT_SECRETS('<integration_name>');
```

Interagir com o servidor MCP usando um cliente MCP personalizado¶

Se você está criando um cliente MCP personalizado, deve usar o ponto de extremidade de URL com o seguinte formato:

https://<account_URl>/api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}

Para obter informações sobre a formatação do URL da sua conta, consulte Identificadores de conta.

Para obter informações sobre como interagir com o servidor MCP, consulte Criar um cliente MCP.

Nota

Atualmente, o servidor MCP do Snowflake oferece suporte apenas aos recursos da ferramenta.

Descobrir e invocar ferramentas¶

Os clientes MCP podem descobrir e invocar ferramentas com as solicitações tools/list e tools/call.

Para descobrir ou invocar ferramentas, emita uma chamada POST como mostrado na solicitação de ferramentas/lista:

Para a ferramenta Analyst, seu cliente passa mensagens na solicitação. A instrução SQL é listada na saída. Você deve passar o nome da ferramenta que está invocando na solicitação como o parâmetro name.

POST /api/v2/databases/<database>/schemas/<schema>/mcp-servers/<name>
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "test-analyst",
            "arguments": {
                "message": "text"
            }
        }
    }

O exemplo a seguir mostra a resposta:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "content": [
            {
                "type": "text",
                "text": "string"
            }
        ]
    }
}

Para solicitações de ferramentas de pesquisa, seu cliente pode passar a consulta e os seguintes argumentos opcionais:

columns
limit

Os resultados da pesquisa e o ID da solicitação são retornados na saída. Você deve passar o nome da ferramenta que está invocando como o parâmetro name na solicitação.

POST /api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "product-search",
            "arguments": {
                "query": "Hotels in NYC",
                "columns": array of strings,
                "limit": int
            }
        }
  }

O exemplo a seguir mostra a resposta:

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
        "results": {}
    }
}

Limitações¶

O servidor MCP gerenciado pelo Snowflake não oferece suporte aos seguintes constructos no protocolo MCP: recursos, prompts, raízes, notificações, negociações de versão, fases do ciclo de vida e amostragem.

Somente respostas sem streaming são compatíveis.