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

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

CUSTOM: ferramenta para UDFs e procedimentos armazenados

Os exemplos a seguir mostram como configurar diferentes tipos de ferramentas:
Para a ferramenta Analyst, seu cliente passa mensagens na solicitação. Você deve passar o nome da ferramenta a ser invocada na solicitação como 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"
      }
    }
  }
Copy
O exemplo a seguir mostra a resposta:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "string"
      }
    ]
  }
}
Copy
Para solicitações de ferramentas de pesquisa, seu cliente pode passar a consulta e os seguintes argumentos opcionais:

columns

filter

limit

Os resultados da pesquisa e o ID da solicitação são listados na saída. Você deve passar o nome da ferramenta a ser invocada na solicitação como name.
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,
        "filter": json,
        "limit": int
      }
    }
  }
Copy
O exemplo a seguir mostra a resposta:
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "results": {}
  }
}
Copy
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."
Copy
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..."
Copy
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

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

Copy

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

Copy

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

Copy

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 exemplo a seguir 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>;

Copy

O exemplo a seguir 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>;

Copy

Controle de acesso¶

Você pode usar os seguintes privilégios para gerenciar o acesso ao objeto MCP e as ferramentas subjacentes

Privilégio	Objeto	Descrição
OWNERSHIP	Objeto MCP	Necessário para atualizar a configuração do objeto
MODIFY	Objeto MCP	Fornece atualizar, descartar, descrever, mostrar e usar (`tools/list` e `tools/call`) na configuração do objeto
USAGE	Objeto MCP	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>'

Copy

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

Nota

Ao efetuar login no Snowflake de seu cliente MCP, você poderá ver uma mensagem de erro Invalid consent request na primeira tentativa. Para resolver isso, encontre o parâmetro de consulta de escopo com o seguinte formato no URL de autorização.

&scope=session%3Arole%3Aall

Altere o escopo de session%3Arole%3Aall para session%3Arole%3Arole name you want to authenticate e reenvie o URL.

Interagir com o servidor MCP usando um cliente MCP personalizado¶

Se você estiver criando um cliente MCP personalizado, as seções a seguir demonstram os pontos de extremidade do Snowflake com os quais seu cliente interage.

Nota

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

Inicialização do servidor MCP¶

Após a autenticação, inicialize o servidor emitindo chamadas GET e POST para o seguinte ponto de extremidade da API:

POST /api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "initialize",
        "params": { "protocolVersion": "2025-06-18" }
    }

Copy

O exemplo a seguir mostra a resposta:

{
    "jsonrpc": "2.0", // passthrough from req
    "id": 1, // passthrough from req
    "result": {
        "proto_version": "2025-06-18",
        "capabilities": {
            "tools": {
                "listChanged": false
            }
        },
        "server_info": {
            "name": "<snowflake-mcp-name>",
            "title": "Snowflake Server: <snowflake-mcp-name>",
            "version": "1.0.0"
        }
    }
}

Copy

Descobrir e invocar ferramentas¶

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

Para descobrir ferramentas, emita uma chamada POST como mostrado em Solicitação tools/list:

POST /api/v2/databases/{database}/schemas/{schema}/mcp-servers/{name}
    {
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/list",
        "params": {}
    }

Copy

O exemplo a seguir mostra a resposta:

{
    "jsonrpc": "2.0", // passthrough from req
    "id": 1, // passthrough from req
    "result": {
        "tools": [ // search
            {
                "name":"product-search",
                "description":"Test search tool",
                "inputSchema": {
                    "type": "object",
                    "description": "A search query and additional parameters for search.",
                    "properties": {
                        "query": {
                            "description": "Unstructured text query.  Exactly one of 'query' or 'multi_index_query' must be specified.",
                            "type": "string"
                        },
                        "columns": {
                            "description": "List of columns to return.",
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        },
                        "filter": {
                            "description": "Filter query.",
                            "type": "object"
                        },
                        "limit": {
                            "description": "Max number of results to return.",
                            "type": "integer",
                            "default": 10
                        }
                    }
                },
                "outputSchema": {
                    "type": "object",
                    "description": "Search results.",
                    "properties": {
                        "results": {
                            "description": "List of result rows.",
                            "type": "array",
                            "items": {
                                "type": "object",
                                "additionalProperties": true,
                                "description": "Map of column names to values (as bytes)."
                            }
                        },
                    "request_id": {
                        "description": "ID of the request.",
                        "type": "string"
                    }
                },
                "required": ["results", "request_id"]
            }
          },
          { // analyst
              "name":"revenue-semantic-view",
              "description":"Test tool",
              "inputSchema": {
                  "type": "object",
                  "description": "A message and additional parameters for Cortex Analyst.",
                  "properties": {
                      "message": {
                          "description": "The user’s question.",
                          "type": "string"
                      }
                  }
              }
          }
        ]
    }
}

Copy

Para invocar uma ferramenta, emita uma chamada POST como mostrado em Solicitação tools/call.

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.