MCP Server

Entenda o Model Context Protocol, como o MCP Server conecta agentes externos à Zild e quais operações da API ele publica.

O que é um MCP Server?

MCP significa Model Context Protocol: um protocolo aberto que padroniza como aplicações de IA se conectam a ferramentas e fontes de contexto. Um MCP Server é o programa que oferece essas capacidades a um cliente compatível. Ele informa quais ferramentas existem, o que cada uma faz e quais argumentos aceita; depois recebe chamadas e devolve os resultados.

Na Zild, isso permite que um agente externo consulte um contato, localize conversas, envie um documento para processamento ou execute um agente da plataforma. O cliente descobre essas operações em um formato comum, em vez de precisar de uma integração própria para cada rota REST.

O MCP organiza a comunicação. O modelo de IA continua sendo executado pela aplicação que o hospeda, e as regras de negócio continuam na Zild API. O servidor não concede novas permissões nem decide sozinho quais ações o usuário deseja executar.

Como cliente, agente e servidor trabalham juntos

  1. Aplicação de IA (host): recebe o pedido do usuário e coordena o uso do modelo e das ferramentas.
  2. Cliente MCP: é o componente dessa aplicação que se conecta ao servidor e troca mensagens do protocolo.
  3. MCP Server da Zild: apresenta o catálogo e traduz a chamada de uma ferramenta em uma requisição à API.
  4. Zild API: aplica autenticação, permissões, resolução de tenant, validação e regras de negócio antes de devolver o resultado.
Usuário → aplicação de IA → cliente MCP
                              ↓
                       Zild MCP Server
                              ↓
                          Zild API
                              ↓
                       Dados do tenant

Por exemplo, ao pedir “consulte o contato 123”, a aplicação pode selecionar a ferramenta correspondente a GET /Contact/{id}, preencher o ID e apresentar a resposta autorizada da Zild ao usuário.

Como MCP e OpenAPI se complementam

Uma API REST define rotas, métodos HTTP, corpos e respostas. O OpenAPI descreve esses contratos de forma estruturada. O MCP oferece ao cliente de IA um catálogo de funções com nome, descrição e schema de entrada, além de uma forma padronizada de executá-las.

Na Zild, o documento OpenAPI final gerado pelo Swagger é a fonte do catálogo. Parâmetros de rota, query e corpo tornam-se argumentos da ferramenta, e a execução chama a rota HTTP original. Assim, a API mantém as regras de negócio e a documentação dos contratos.

O protocolo também permite publicar resources (fontes de contexto) e prompts (modelos reutilizáveis de interação). A primeira versão da Zild publica tools, geradas das operações da API; não há catálogo próprio de resources ou prompts nesta implementação.

Saiba mais na arquitetura oficial do MCP e nos conceitos de servidores MCP.

O que o MCP da Zild expõe

A análise do OpenAPI incluído neste site identificou 137 operações em 79 rotas: 51 GET, 42 POST, 22 PUT e 22 DELETE. Pelo adaptador implementado, cada operação desse documento corresponde a uma ferramenta.

O catálogo abrange CRM, agentes, voz, Insight, Assist, conversas, documentos, Flow, conexões MCP, departamentos, cotas, consumo e webhooks. Ele inclui consultas e ações que alteram dados ou iniciam comunicação com outras pessoas. A autorização é verificada em cada execução.

Consulte o catálogo completo de operações MCP, com nomes previstos das ferramentas, métodos, rotas e links para os contratos. Os números descrevem o arquivo analisado; o catálogo de um ambiente depende do Swagger da versão implantada. O endpoint continua desativado por padrão até ser habilitado pelo operador.

Conexão e autenticação

Configure um cliente compatível com Streamable HTTP para acessar /mcp na origem da Zild API habilitada. O transporte não mantém sessões persistentes. Envie uma das credenciais existentes em cada requisição:

X-API-Key: YOUR_USER_API_KEY

Authorization: Bearer YOUR_ACCESS_TOKEN

Use uma URL HTTPS fornecida pelo operador do ambiente. A primeira versão não implementa descoberta OAuth, consentimento ou emissão de tokens para novos clientes MCP. O cliente precisa permitir a configuração do header de autenticação.

Descoberta e execução de ferramentas

O catálogo é gerado pelo mesmo Swagger/OpenAPI da documentação da API. Ações ocultas e filtros de publicação são respeitados; cada operação publicada gera uma ferramenta, incluindo operações de escrita.

No cliente, descubra as ferramentas com tools/list e execute a ferramenta escolhida com tools/call, usando o nome e o inputSchema retornados. Os nomes seguem zild_<método>_<rota-normalizada>_<hash>.

O catálogo é compartilhado entre clientes autenticados. A execução passa novamente pela autenticação, pelas permissões e pela resolução de tenant da API. Uma ferramenta aparecer no catálogo não concede acesso ao recurso.

Argumentos e arquivos

Preencha apenas os grupos presentes no schema da ferramenta: path, query, body e, quando publicado, header. Exemplo ilustrativo:

{
  "path": {
    "id": 123
  },
  "query": {
    "page": 1
  },
  "body": {
    "name": "Exemplo"
  }
}

Há suporte a JSON, multipart/form-data e application/x-www-form-urlencoded. Arquivos usam fileName, contentBase64 e contentType no campo de arquivo do body. Headers de autenticação são enviados pelo transporte, não pelos argumentos da ferramenta.

Limites e respostas

  • Requisição MCP: 16 MiB; arquivo individual: 10 MiB.
  • Resposta da API: 2 MiB; use filtros e paginação.
  • Timeout: 120 segundos.
  • Limite padrão: 60 requisições por minuto por credencial, por instância, configurável pelo operador.

Resultados preservam o JSON da API em conteúdo textual. Respostas HTTP sem sucesso retornam isError com o status HTTP. Não há repetição automática nem garantia adicional de idempotência; após uma falha ou timeout em uma escrita, consulte o resultado antes de repetir.

Ativação pelo operador

Configure o ambiente da Zild.Api:

McpServer__Enabled=true
McpServer__ApiBaseUrl=https://<host-da-zild-api>/
McpServer__RequestsPerMinute=60

ApiBaseUrl deve apontar para a mesma API e terminar em /. Inclua o prefixo de hospedagem, quando houver. A URL deve representar o mesmo recurso protegido e a mesma audiência de autenticação. Consulte também a Zild API para os contratos das operações.