# MCP Server Entenda o Model Context Protocol, como o MCP Server conecta agentes externos à Zild e quais operações da API ele publica. Source: https://zild.ai/pt-BR/docs/mcp-server/introduction ## 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 - **Aplicação de IA (host):** recebe o pedido do usuário e coordena o uso do modelo e das ferramentas. - **Cliente MCP:** é o componente dessa aplicação que se conecta ao servidor e troca mensagens do protocolo. - **MCP Server da Zild:** apresenta o catálogo e traduz a chamada de uma ferramenta em uma requisição à API. - **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](https://modelcontextprotocol.io/docs/learn/architecture) e nos [conceitos de servidores MCP](https://modelcontextprotocol.io/docs/learn/server-concepts). ## O que o MCP da Zild expõe A análise do [OpenAPI incluído neste site](/openapi.json) 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](/pt-BR/docs/mcp-server/catalog), 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___`. 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:/// 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](/pt-BR/docs/api-reference/introduction) para os contratos das operações.