> For the complete documentation index, see [llms.txt](https://docs.poweromni.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.poweromni.ai/administracao-e-configuracao/artefatos/conectores/mcp.md).

# MCP

O conector MCP permite conectar um agente do Power Omni a um servidor compatível com o Model Context Protocol.

Na prática, ele funciona como uma ponte entre o agente e ferramentas externas. Essas ferramentas podem estar em um servidor próprio, em uma API preparada para MCP ou em um serviço mantido por outro fornecedor.

### Quando usar o conector MCP?

Use o conector MCP quando você já possui um servidor MCP disponível e quer permitir que o agente execute as ferramentas publicadas por esse servidor.

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FODF04qxBkKBfbdQAdWQn%2Fimage.png?alt=media&amp;token=15cf2f35-fbfd-4e9b-8e2e-f9ce330cacca" alt=""><figcaption></figcaption></figure>

Alguns exemplos de uso:

* consultar dados em um sistema externo;
* executar ações em uma API própria;
* integrar o agente a ferramentas internas da empresa.

Esse conector é indicado para cenários mais técnicos, em que já existe um servidor MCP de algum sistema utilizado pela empresa ou uma equipe responsável por criar e manter esse servidor.

### Como funciona no Power Omni

Ao criar o conector, você informa a URL do servidor MCP, define um nome para o servidor, escolhe o tipo de autenticação e configura quais ferramentas poderão ser utilizadas.

Também é possível encaminhar o e-mail do usuário autenticado no Power Omni para o servidor MCP. Esse recurso pode ser usado quando o servidor precisa identificar qual usuário iniciou determinada chamada.

### Criando um conector MCP

Para criar um conector MCP, acesse:

`Configurações → Artefatos → Conectores → Criar Conector`

Depois, selecione o tipo:

`Servidor MCP`

Preencha os campos de acordo com o servidor que deseja conectar.

### Campos do conector

<table><thead><tr><th width="315">Campo</th><th>Como preencher</th></tr></thead><tbody><tr><td>Tipo de Conector</td><td>Selecione <code>Servidor MCP</code>.</td></tr><tr><td>Projeto</td><td>Escolha o projeto onde o conector será criado.</td></tr><tr><td>Nome</td><td>Informe um nome simples para identificar o conector no Power Omni.</td></tr><tr><td>Descrição</td><td>Explique quando e como o agente deve utilizar esse conector.</td></tr><tr><td>Label do Servidor</td><td>Informe um identificador único para o servidor MCP. Exemplo: <code>meu_servidor_mcp</code>.</td></tr><tr><td>URL do Servidor</td><td>Informe a URL do endpoint MCP. Exemplo: <code>https://exemplo.com/api/mcp</code>.</td></tr><tr><td>Autenticação</td><td>Escolha <code>Nenhuma</code> ou <code>API Key</code>, de acordo com o servidor.</td></tr><tr><td>Enviar e-mail do usuário logado</td><td>Habilite quando o e-mail do usuário autenticado precisar ser enviado ao servidor MCP.</td></tr><tr><td>Nome do header de e-mail</td><td>Informe o nome do header HTTP utilizado pelo servidor para receber o e-mail.</td></tr><tr><td>Tools Permitidas</td><td>Defina se o conector poderá utilizar todas as ferramentas, somente ferramentas selecionadas ou nenhuma ferramenta do servidor.</td></tr><tr><td>Política de Aprovação</td><td>Defina como as chamadas das ferramentas MCP serão aprovadas antes da execução.</td></tr></tbody></table>

### Label do Servidor

O `Label do Servidor` é o identificador usado para reconhecer aquele servidor MCP.

Use um nome curto, sem espaços e fácil de entender.

Exemplos:

```
github_mcp financeiro_mcp crm_mcp meu_servidor_mcp
```

O ideal é que o nome indique qual sistema ou finalidade aquele MCP representa.

### URL do Servidor

A `URL do Servidor` deve apontar para o endpoint MCP remoto.

Exemplo:

```
https://exemplo.com/api/mcp
```

O endpoint precisa estar acessível pelo Power Omni.

Se a URL estiver protegida por uma rede privada, firewall, bloqueio de IP ou por um tipo de autenticação não suportado pelo conector, a comunicação com o servidor pode falhar.

### Autenticação

O Power Omni permite configurar o conector MCP sem autenticação ou utilizando uma API Key.

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FSedwkWl0AbCwAaE9UCoG%2Fimage.png?alt=media&amp;token=6797f24b-cba3-4cd4-a265-4ebb444a9280" alt=""><figcaption></figcaption></figure>

#### Nenhuma

Use essa opção quando o servidor MCP não exigir chave, token ou outra credencial.

Esse modo pode ser utilizado, por exemplo, em servidores públicos ou em ambientes onde a proteção do endpoint acontece em outra camada.

#### API Key

Use essa opção quando o servidor MCP exigir uma chave de acesso.

Ao selecionar `API Key`, o Power Omni exibirá a área de configuração da conexão.

Você pode importar uma conexão existente ou criar uma nova.

Para criar uma conexão, informe:

<table><thead><tr><th width="241">Campo</th><th>Como preencher</th></tr></thead><tbody><tr><td>Nome da Conexão</td><td>Dê um nome para identificar a credencial.</td></tr><tr><td>Token / API Key</td><td>Informe a chave ou token exigido pelo servidor MCP.</td></tr></tbody></table>

### Enviar e-mail do usuário logado

Ative a opção `Enviar e-mail do usuário logado` quando o servidor MCP precisar identificar qual usuário do Power Omni realizou a chamada.

Quando essa opção estiver habilitada, o e-mail do usuário autenticado será enviado ao servidor MCP em cada chamada de ferramenta.

Esse recurso pode ser utilizado em situações como:

* identificação do usuário no sistema de destino;
* aplicação de permissões ou regras de acesso;
* filtragem de informações de acordo com o usuário;
* registro de auditoria das operações executadas.

O usuário não precisa informar seu endereço de e-mail durante a execução. O Power Omni obtém essa informação do usuário autenticado e preenche o valor automaticamente.

### Nome do header de e-mail

Ao habilitar o envio do e-mail, será possível configurar o campo `Nome do header de e-mail`.

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FXAfiPzego5ZUvMbabpmu%2Fimage.png?alt=media&amp;token=cc4c5d3a-ecff-4dd0-aaf3-6b70e25b037c" alt=""><figcaption></figcaption></figure>

Esse campo define qual header HTTP o servidor MCP utilizará para receber o e-mail do usuário.

Por padrão, você pode utilizar:

```
PowerOMNI-User-Email
```

Nesse cenário, uma chamada poderá chegar ao servidor MCP com um header semelhante a:

```
PowerOMNI-User-Email: usuario@empresa.com
```

Somente o nome do header é configurado nessa tela.

O valor é preenchido automaticamente pelo Power Omni com o e-mail do usuário autenticado e não pode ser definido manualmente pelo usuário.

Se o seu servidor MCP espera outro nome de header, altere o campo para o nome utilizado pela aplicação.

Por exemplo:

```
X-User-Email
```

Nesse caso, o Power Omni enviará:

```
X-User-Email: usuario@empresa.com
```

O servidor MCP precisa estar preparado para receber e interpretar o header configurado.

### Tools Permitidas

A configuração `Tools Permitidas` controla quais ferramentas disponibilizadas pelo servidor MCP poderão ser utilizadas pelo agente.

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2FaC2YASETPHhFCPsXjO4v%2Fimage.png?alt=media&amp;token=d98f4c96-7f7d-415f-b561-3c7507ce4fb8" alt=""><figcaption></figcaption></figure>

O Power Omni oferece três opções.

#### Todas as ferramentas

Permite utilizar todas as ferramentas disponibilizadas pelo servidor MCP.

Essa opção é útil quando o agente pode utilizar todo o conjunto de ferramentas daquele servidor.

#### Apenas as selecionadas

Permite escolher individualmente quais ferramentas do servidor MCP poderão ser utilizadas.

Essa opção é indicada quando o servidor possui várias ferramentas, mas o agente deve ter acesso somente a uma parte delas.

Por exemplo, um servidor pode disponibilizar:

```
consultar_cliente listar_pedidos cancelar_pedido alterar_cliente
```

Caso o agente precise apenas consultar informações, você pode liberar:

```
consultar_cliente listar_pedidos
```

As demais ferramentas não ficarão disponíveis para uso pelo agente.

#### Nenhuma ferramenta

Impede a utilização das ferramentas disponibilizadas por aquele servidor MCP.

Essa configuração pode ser utilizada quando o conector precisa permanecer cadastrado, mas suas ferramentas não devem ficar disponíveis para execução naquele momento.

### Política de Aprovação

A `Política de Aprovação` define se uma chamada para uma ferramenta MCP pode ser executada automaticamente ou se precisa passar por uma etapa de aprovação.

<figure><img src="https://1296644906-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLGvDlIVKG3lx8yU6pzIF%2Fuploads%2F7Yr08RAhMJEYwiVjMpY8%2Fimage.png?alt=media&amp;token=3b5a377d-4081-432c-9ac8-1269d7428ec0" alt=""><figcaption></figcaption></figure>

Quando a opção estiver configurada como:

```
Nunca (execução automática)
```

as ferramentas poderão ser executadas sem solicitar aprovação antes de cada chamada.

A escolha da política deve considerar o que cada ferramenta pode fazer.

### Testando o conector

Depois de salvar o conector, **associe-o a um agente** e faça alguns testes simples.

Você pode começar perguntando:

```
Quais ferramentas estão disponíveis?
```

Confira se as ferramentas apresentadas correspondem à configuração definida em `Tools Permitidas`.

Depois, teste uma ferramenta específica.

Exemplo:

```
Consulte os dados do cliente João usando a ferramenta disponível.
```

Se você ativou `Enviar e-mail do usuário logado`, também verifique no servidor MCP se o header configurado está sendo recebido corretamente.

Por exemplo:

```
PowerOMNI-User-Email: usuario@empresa.com
```

### Preciso de ajuda?

Se tiver alguma dúvida para configurar um servidor MCP, validar a autenticação, definir as ferramentas permitidas, configurar o envio do e-mail do usuário ou entender qual política de aprovação utilizar, procure o suporte do Power Omni.