Desenvolvimento de servidor MCP: faça da Agentic AI o "cliente zero" da sua API

As equipes de engenharia do Red Hat Trusted Profile Analyzer (TPA) e do Trustify decidiram testar o Model Context Protocol (MCP). Este artigo mostrará os desafios que enfrentamos em nossa jornada. Assim, vamos ajudar outras pessoas que querem tentar algo semelhante.

Para contextualizar, o Red Hat Trusted Profile Analyzer (TPA) é uma solução da Red Hat para gerenciamento de listas de materiais de software (SBOM). Ela armazena SBOMs e correlaciona seus pacotes com vulnerabilidades públicas conhecidas. Ele é baseado no projeto upstream Trustify.

Em geral, sua arquitetura é bastante "tradicional":

• O front-end é desenvolvido usando os componentes React e PatternFly (trustify-ui).
• O back-end é desenvolvido com Rust, ele se conecta a uma instância de banco de dados e armazena as SBOMs em um armazenamento compatível com S3.

As principais etapas realizadas foram:

1. Desenvolver a integração do servidor MCP com TPA/Trustify
2. Definir as descrições da ferramenta do servidor MCP
3. Projetar os parâmetros da ferramenta do servidor MCP

Aqui falamos sobre as considerações em cada fase, e o resultado final é o servidor MCP disponível no GitHub. 

Desenvolver a integração do servidor MCP com TPA/Trustify

Antes de explicarmos como definimos a integração entre o servidor MCP e o Trustify, enfrentamos um dilema típico na vida de um engenheiro de software: qual biblioteca vou adotar para este projeto? Devo começar do zero e desenvolver tudo por conta própria?

Como verdadeiros defensores do open source, analisamos o cenário atual das bibliotecas do Rust (o Trustify foi desenvolvido principalmente em Rust, por isso era nossa opção recomendada) para implementar um servidor MCP.

Nossa pesquisa foi rápida porque descobrimos que o MCP fornece algumas bibliotecas oficiais em sua organização do GitHub, e entre elas havia uma desenvolvida com Rust.

Essa biblioteca, além de incluir o código necessário para oferecer suporte ao desenvolvimento de um servidor MCP, também oferece ótimos exemplos iniciais.

Ficou imediatamente claro que, além dos detalhes específicos da biblioteca para executar o servidor MCP e definir as ferramentas disponíveis com seus parâmetros, tínhamos que decidir como o servidor MCP teria acesso aos dados de "back-end".

Avaliamos duas opções diferentes. O servidor MCP pode recuperar os dados da seguinte maneira:

• Conectando-se diretamente ao banco de dados (DB) onde o back-end do Trustify armazena os dados; ou
• Chamando os endpoints REST fornecidos pelo back-end do Trustify

Como você pode imaginar, ambos têm prós e contras, o que gerou uma discussão acalorada que resumirei aqui.

Vantagens de se conectar diretamente ao banco de dados:

1. Acesso de alto desempenho aos dados
2. Oportunidade de implementar uma abordagem de conversão de texto em SQL

Desvantagens:

1. O servidor MCP deve estar no mesmo nível de arquitetura que o back-end
2. A duplicação de código seria necessária para gerenciar o acesso aos dados em comparação com o código no back-end
3. Seria necessário gerenciar o formato dos dados para definir as saídas das chamadas das ferramentas do MCP

Vantagens de chamar os endpoints REST:

1. As chamadas seguem a autenticação e a autorização já em vigor nas APIs de back-end
2. Os dados disponíveis no servidor MCP serão totalmente consistentes com o que está disponível na IU, já que usam a mesma fonte de dados
3. Saída JSON disponível gratuitamente simplesmente enviando a saída retornada das APIs de back-end

Desvantagens:

1. Desempenho mais lento devido à necessidade de passar por mais camadas de arquitetura

No final, decidimos chamar os endpoints REST das ferramentas do servidor MCP, porque a desvantagem de precisar executar o servidor MCP junto ao back-end e próximo o suficiente do banco de dados poderia ser um obstáculo, especialmente quando o servidor MCP com transporte via stdio é executado localmente nos hosts dos desenvolvedores.

Ter todos os dados formatados "de graça" em respostas JSON foi outro benefício nessa fase inicial de desenvolvimento.

Definir as descrições da ferramenta do servidor MCP

Depois que decidimos que as ferramentas do servidor MCP chamariam as APIs de back-end, tivemos que decidir como descrever as diferentes ferramentas. Queríamos que, na primeira iteração, cada ferramenta MCP chamasse um único endpoint de API de back-end.

Considerando que o Trustify documenta os endpoints disponíveis usando o arquivo openapi.yaml da OpenAPI, decidimos usar a descrição e as definições dos endpoints da OpenAPI como a descrição da ferramenta MCP. Assim, poderíamos avaliar a qualidade da documentação desses endpoints para nossos usuários. Isso transformou a Agentic AI no "cliente zero" das nossas APIs.

Tudo isso foi feito com a abordagem de melhoria contínua: se as descrições das APIs do Trustify são boas o suficiente para um LLM gerenciar, nossos usuários também devem ser capazes de entender essa documentação.

Seguir essa abordagem está nos ajudando a melhorar cada endpoint e nos levou à nossa próxima decisão de design.

Projetar os parâmetros das ferramentas do servidor MCP

Neste ponto, enfrentamos um problema relacionado aos parâmetros de entrada para a invocação da ferramenta e, para entendê-lo, precisávamos voltar um passo para trás. O endpoint do Trustify para recuperar uma lista de entidades aceita um parâmetro de consulta q. Esse parâmetro permite que os usuários especifiquem uma consulta com base na gramática definida nas especificações da OpenAPI. 

As opções que tínhamos eram:

1. Expor diretamente o parâmetro "q" path do endpoint como o parâmetro de entrada da ferramenta MCP
2. Expor os campos internos disponíveis para criar o valor da consulta para o parâmetro "q" como os parâmetros de entrada da ferramenta MCP

Testamos ambas as abordagens.

A primeira abordagem exige uma descrição forte e detalhada do parâmetro de consulta que, no momento, a especificação da OpenAPI não fornece. Acreditamos que uma lista abrangente de campos consultáveis deva ser parte obrigatória da documentação, e não opcional. Seria útil se todos os usuários tivessem acesso a essas informações.

Essa segunda abordagem simplifica o processo para o agente de IA. Ao listar explicitamente os parâmetros a serem consultados, como gravidade da vulnerabilidade, data de publicação ou descrição, as informações ficam mais fáceis de processar para o LLM. Isso elimina a necessidade de o LLM interpretar primeiro a gramática de uma consulta, o que pode ser uma etapa complexa na primeira abordagem.

Outra consideração é que listar todos os parâmetros disponíveis explicitamente na ferramenta MCP exige um trabalho contínuo para manter a consistência com a implementação real do endpoint de back-end. Por outro lado, expor apenas um subconjunto dos parâmetros disponíveis tem o efeito de reduzir a versatilidade da ferramenta, sem garantia de reduzir o custo de manutenção.

Decidimos continuar usando um parâmetro de consulta "q" para a ferramenta MCP e aprimoraremos sua descrição na definição da OpenAPI. Assim, todos os usuários podem se beneficiar.

Considerações finais

Ao projetar um servidor MCP, adotamos a seguinte abordagem:

• O servidor MCP aproveita as APIs existentes
• O servidor MCP aproveita a documentação existente da OpenAPI
• As ferramentas do servidor MCP expõem o mesmo parâmetro que o endpoint remoto da API está esperando

Como mencionamos anteriormente, o resultado final está disponível no GitHub.