Servidor MCP gerenciado pelo Snowflake¶

Visão geral¶

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¶

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.

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

2. 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"
     $$
   

   Copy

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:

Analyst toolSearch toolSQL execution toolAgent toolCustom tool

Usando a ferramenta Analyst, seu cliente pode gerar texto de SQL. 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"

Copy

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

-- 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))
$$;

-- 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))
$$;

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"
  $$;

1. 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;
   

   Copy

   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 |
   

2. Para descrever um servidor MCP, use o seguinte comando:

   DESCRIBE MCP SERVER <server_name>;
   

   Copy

   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 |
   

3. Para descartar um servidor MCP, use o seguinte comando:

   DROP MCP SERVER <server_name>;
   

   Copy

Controle de acesso¶

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

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.

1. 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>'
   

   Copy

2. 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>');
   

   Copy

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.

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"
            }
        }
    }

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

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
            }
        }
  }

{
    "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.