# MCP Server Trigger

## **Visão geral**

O **MCP Server** é um trigger que permite que um pipeline da Digibee receba e processe solicitações provenientes de um **cliente MCP (Model Context Protocol)**.

Ele atua como ponto de entrada para eventos ou ações iniciadas por ferramentas externas conectadas por meio do protocolo MCP, como assistentes de IA ou serviços de automação que se comunicam com a Digibee.

### **Para que serve**

É usado quando você deseja:

* Permitir que serviços de IA ou externos (como um assistente compatível com MCP) executem uma ação, obtenham mais contexto ou interajam com um pipeline da Digibee.
* Garantir a aplicação de playbooks e processos de negócio para tornar seu agente mais inteligente.
  * Agentes têm dificuldade em seguir orientações não estruturadas. A Digibee garante a execução correta passo a passo.
* Garantir que seu agente siga regras e políticas de negócio.
  * Você pode externalizar suas regras em pipelines MCP. Isso garante decisões determinísticas e auditáveis.

### **Como funciona**

1. O **cliente MCP** envia uma solicitação que corresponde à configuração do trigger.
2. O **MCP Server Trigger** inicia o pipeline e fornece o payload de entrada.
3. O pipeline executa sua lógica (transformações, integrações, e assim por diante).
4. O resultado é encapsulado em um **objeto `content`**, conforme exigido pelo protocolo oficial do MCP. Isso garante que o agente de IA receba as informações no formato de texto ou imagem esperado.

## **Configuração das ferramentas**

Para começar a configurar o trigger, é necessário adicionar ferramentas. Cada ferramenta exposta por um servidor MCP inclui um conjunto de campos principais que definem sua identidade, propósito, permissões e estrutura de dados.

### **Adicionando uma nova ferramenta**

1. Acesse a seção **Ferramentas do MCP Server**.
2. Clique em **Adicionar Ferramentas**.
3. Preencha os campos descritos abaixo.
4. Após salvar, a ferramenta aparecerá na **Lista de Ferramentas**, onde você pode adicionar, editar ou excluir entradas.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2Fz2AuiP6OeQjhWNPoxamy%2Fpt-add-ferramentas-mcp-server.gif?alt=media&#x26;token=039b4c5b-9da3-4ea0-8491-a72aa113c0b8" alt=""><figcaption></figcaption></figure>

### **Campos da ferramenta**

#### **Nome da Ferramenta**

Identificador exclusivo da ferramenta. Deve ser conciso, descritivo e geralmente utilizar *snake\_case*.

**Exemplo:** `search_web`

#### **Descrição**

Resumo curto e claro do que a ferramenta faz. Ajuda o modelo e os usuários a entenderem seu propósito.

**Exemplo:** Executa uma pesquisa na web e retorna os principais resultados.

#### Escopos

Define as permissões que essa ferramenta requer em tempo de execução. Os escopos são incorporados ao token JWT com escopo quando um agente invoca essa ferramenta. Este campo é opcional. Digite um escopo e pressione **Enter** ou **Tab** para adicioná-lo como uma tag.

**Exemplo:** `read:web`, `write:logs`

{% hint style="warning" %}
Pipelines criados antes da release de 27 de janeiro de 2026 que utilizam o MCP Server Trigger devem ser reconfigurados devido à inclusão dos Scopes. Abra a configuração do trigger e clique em **Salvar** novamente.

Por segurança, recomendamos gerar uma cópia de seus **Block Executions** antes de realizar esta atualização.
{% endhint %}

#### **Configuração de Schema**

Você pode definir como sua ferramenta lida com dados de **entrada** e **saída** usando JSON Schemas. Esses schemas descrevem a estrutura esperada, os tipos de dados e as regras de validação.

A configuração se aplica a duas seções:

* **Schema de Entrada:** Define a estrutura dos dados recebidos pela ferramenta.
* **Schema de Saída:** (Opcional) Define a estrutura dos dados retornados pela ferramenta.

Ambos podem ser configurados de duas formas:

**Opção 1: Assistente**

Use o assistente para orientar sua configuração clicando em **Adicionar Propriedade** e preenchendo os parâmetros:

* **Nome:** Define o nome da propriedade dentro do objeto JSON.
* **Tipo:** Especifica o tipo de dado (`string`, `number`, `boolean`, `array` ou `object`).
* **Obrigatório:** Indica se o campo é obrigatório.
* **Descrição:** Descreve o propósito ou significado da propriedade.
* **Valores Enum:** (Aplicável apenas ao tipo `string`) Lista os valores permitidos para a propriedade.
* **Tipo do Item do Array:** (Aplicável apenas ao tipo `array`) Define o tipo de dado dos elementos do array (`string`, `number`, `boolean` ou `array`).
* **Propriedades do Objeto:** (Aplicável apenas ao tipo `object`) Define o conjunto de propriedades contidas dentro do objeto.

**Exemplo: Schema de Entrada**

| Nome  | Tipo   | Obrigatório | Descrição                                               | Valores Enum |
| ----- | ------ | ----------- | ------------------------------------------------------- | ------------ |
| query | string | ✅ Sim       | O termo de pesquisa ou palavras-chave a serem buscadas. | —            |
| limit | number | ❌ Não       | Número de resultados a serem retornados.                | N/A          |

**JSON Schema resultante**

```json
{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "O termo de pesquisa ou palavras-chave a serem buscadas."
    },
    "limit": {
      "type": "integer",
      "description": "Número de resultados a serem retornados.",
      "default": 5
    }
  },
  "required": ["query"]
}
```

**Exemplo: Schema de Saída**

| Nome    | Tipo  | Obrigatório | Descrição                                             | Tipo do Item do Array |
| ------- | ----- | ----------- | ----------------------------------------------------- | --------------------- |
| results | array | ❌ Não       | Lista de URLs correspondentes à consulta de pesquisa. | string                |

**JSON Schema resultante**

```json
{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Lista de URLs correspondentes à consulta de pesquisa."
    }
  }
}
```

**Opção 2: Schema**

Como alternativa, insira o JSON Schema diretamente no campo fornecido.

## **Configuração de parâmetros**

<table data-full-width="true"><thead><tr><th>Parâmetro</th><th>Descrição</th><th>Tipo de dado</th><th>Valor padrão</th></tr></thead><tbody><tr><td><strong>Server Name</strong></td><td>Nome do servidor MCP. Usado apenas para referência.</td><td>String</td><td>N/A</td></tr><tr><td><strong>Description</strong></td><td>Breve descrição para identificar o servidor MCP.</td><td>String</td><td>N/A</td></tr><tr><td><strong>Maximum Timeout</strong></td><td>Tempo máximo (em milissegundos) para o pipeline processar as informações antes de retornar uma resposta. Limite: <code>900000</code> ms.</td><td>Integer</td><td><code>30000</code></td></tr><tr><td><strong>The Maximum Allowed Request Size In Mb</strong></td><td>Tamanho máximo do payload em megabytes. O tamanho máximo configurável é de 5 MB.</td><td>Integer</td><td><code>5</code></td></tr><tr><td><strong>External API</strong></td><td>Se ativado, o servidor MCP torna-se acessível por meio do gateway externo da Digibee, permitindo comunicação pela Internet pública.</td><td>Boolean</td><td>True</td></tr><tr><td><strong>Internal API</strong></td><td>Se ativado, expõe o servidor MCP por meio do gateway interno da Digibee, restringindo o acesso apenas à rede interna. As opções <strong>External API</strong> e <strong>Internal API</strong> podem estar ativas simultaneamente.</td><td>Boolean</td><td>False</td></tr><tr><td><strong>API Key</strong></td><td>Se ativado, o endpoint só pode ser acessado com uma chave de API configurada na Digibee Integration Platform.</td><td>Boolean</td><td>False</td></tr><tr><td><strong>External JWT</strong></td><td>Se habilitado, o MCP Server valida tokens JWT de provedores de identidade externos (ex: Auth0, Azure AD, Okta) recebidos através do header <code>externalJWT</code>.</td><td>Boolean</td><td>False</td></tr><tr><td><strong>Public Key</strong></td><td>A chave pública do provedor externo. Ela é usada para validar a assinatura do token.</td><td>String</td><td>N/A</td></tr><tr><td><strong>JSW Algorithm (JWA)</strong></td><td>Especifica o algoritmo de criptografia usado para validar a assinatura digital do token JWT.</td><td>String</td><td>ES256</td></tr><tr><td><strong>Token JWT</strong></td><td>Se habilitado, o endpoint só pode ser acessado quando um token JWT gerado por outro endpoint for fornecido. Para mais informações, consulte o artigo sobre a <a href="../../connectors/security/digibee-jwt/digibee-jwt-implementation">implementação de JWT</a>.</td><td>Boolean</td><td>False</td></tr><tr><td><strong>Documentation</strong></td><td>Campo opcional para descrever a configuração do trigger e quaisquer regras de negócio relevantes.</td><td>String</td><td>N/A</td></tr></tbody></table>

## **Representação visual das ferramentas**

Após salvar a configuração do trigger, uma **representação visual das ferramentas** é exibida no pipeline.

<figure><img src="https://3268428548-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSKBJ6ZiEWBU93x170HH4%2Fuploads%2Fkhk7DqHYnRdcTCjuhaJg%2Frepresenta%C3%A7%C3%A3o-visual-mcp-server.png?alt=media&#x26;token=1132f4ff-b278-4c48-bc48-f58768d8f9a6" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
As ferramentas só podem ser editadas por meio do formulário de configuração do trigger. Quaisquer alterações feitas são refletidas imediatamente no pipeline após salvar.
{% endhint %}

Cada ferramenta está conectada a um conector [**Block Execution**](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/connectors/logic/block-execution). Esse conector é projetado para **separar logicamente a integração em subfluxos diferentes**, facilitando o gerenciamento do pipeline. Para concluir a configuração, você deve criar os fluxos para cada rota dentro dos [**subfluxos OnProcess e OnException**](https://app.gitbook.com/s/cO0A6g1dOsu8BiHYqO67/development-cycle/build-overview/pipelines/subpipelines).

Independentemente da quantidade de ferramentas configuradas, sempre haverá uma **rota padrão** para casos em que uma ferramenta não seja encontrada. Você pode configurar essa rota para tratar adequadamente as ferramentas ausentes.

{% hint style="warning" %}
**Observações importantes:**

* Se você criar o fluxo antes de configurar o trigger, os conectores existentes serão desconectados assim que o trigger for salvo.
* Excluir uma ferramenta da **Lista de Ferramentas** desconectará o conector **Block Execution** correspondente do fluxo principal.
  {% endhint %}