MCP vs REST: quando cada um ganha na integração de agentes de IA

#MCP vs REST: quando cada um ganha na integração de agentes de IA

Tratar o MCP e o REST como alternativas é partir da premissa errada. Estão em camadas diferentes: o REST é transporte mais convenções, o MCP é um protocolo tipado pensado para um consumidor LLM. A decisão real é com que superfície fala cada consumidor e como é que as duas superfícies partilham um backend. Este artigo apresenta o enquadramento que uso quando defino o âmbito de integrações de IA em projetos WordPress e WooCommerce.

Este artigo está ligado ao pilar desenvolvimento de servidores MCP.

#Em resumo

• O MCP e o REST complementam-se, não são alternativas.
• O REST ganha com clientes determinísticos, com um conjunto de ações fixo e documentação OpenAPI.
• O MCP ganha com agentes LLM que precisam de descobrir ferramentas em tempo de execução e de envelopes tipados para ações que alteram dados.
• A configuração por defeito em produção é o REST como system of record e o MCP como superfície para agentes à frente.
• O mesmo backend, duas superfícies, uma única fonte de verdade.

#O que é o MCP e o que é uma API REST

REST. Um estilo arquitetural da tese de doutoramento de Roy Fielding de 2000 (a fonte da tese), normalmente expresso sobre HTTP com verbos e URLs de recursos. O WordPress expõe uma API REST em /wp-json/wp/v2/ (manual da API REST do WordPress); o WooCommerce estende-a em /wp-json/wc/v3/. A documentação costuma ser OpenAPI (especificação OpenAPI) e os SDKs são gerados a partir do esquema em tempo de build.

MCP. Um protocolo baseado em JSON-RPC 2.0 que a Anthropic anunciou a 25 de novembro de 2024 (anúncio da Anthropic) para ligar hosts LLM (Claude Desktop, IDEs, ambientes de agentes próprios) a dados e ferramentas. Três primitivas: tools (funções invocáveis), resources (documentos só de leitura), prompts (modelos fornecidos pelo servidor). A descoberta acontece em tempo de execução via tools/list; o agente aprende as capacidades disponíveis em cada sessão.

Vistas de longe, as formas parecem semelhantes. Sob carga, afastam-se depressa.

#Matriz de decisão entre MCP e API REST

Seis fatores que avalio antes de escolher a superfície para uma determinada ação:

A matriz diz-me qual o protocolo preferível para uma ação, não para a API inteira. A maioria dos projetos acaba dividida.

#Quando usar uma API REST em vez de MCP

Uma loja online a obter uma página de categoria. Programada contra /wp-json/wp/v2/categories?slug=widgets. A forma é conhecida, os cabeçalhos de cache fazem o seu trabalho e a CDN pode guardar em cache por URL.

A integração de ERP de um parceiro a sincronizar o stock diariamente. A equipa do parceiro lê o OpenAPI, gera um SDK tipado e agenda um cron para as 03:00 UTC. Quer URLs estáveis, formas de resposta previsíveis e códigos de estado HTTP. O MCP acrescentaria complexidade sem valor.

Tráfego público e anónimo de leitura. Um crawler de SEO a percorrer páginas de produto, um agregador de comparação de preços a puxar feeds de produtos. O REST com rate limiting trata este caso com a infraestrutura mais madura que existe.

Entrega de webhooks. O WooCommerce dispara woocommerce_order_status_completed para um endpoint do parceiro. Esse endpoint é um recetor REST. O MCP é a forma errada, porque o agente não está no circuito; o recetor é um sistema determinístico.

#Quando usar MCP em vez de REST

Um agente LLM a agir sobre a intenção livre do utilizador. “Encontra-me um casaco impermeável por menos de 200 euros que seja enviado para Lisboa.” O agente não sabe de antemão que combinação de filtros aplicar; tem de examinar as ferramentas disponíveis, ler as descrições e decidir. O REST dá-lhe 47 parâmetros de query distribuídos por três endpoints e nenhum sinal sobre quais usar.

Ações que alteram dados em que a idempotência importa. Criar uma encomenda a partir de um LLM é o exemplo mais evidente. A ferramenta MCP order.intent, com um esquema de entrada tipado e uma chave de idempotência, é um contrato mais apertado do que uma chamada livre a POST /wp-json/wc/v3/orders. As novas tentativas são seguras por desenho, não por convenção.

Uma superfície de ferramentas que muda com frequência. Acrescentar um novo filtro de pesquisa ou um novo tipo de produto significa publicar uma nova ferramenta MCP com um bloco describe; o agente apanha-a no tools/list seguinte sem alterações de código do lado do agente. Com REST, cada alteração é uma versão coordenada do SDK.

Fluxos de agente em vários passos. “Verifica se o SKU AC-101 está em stock; se não estiver, sugere três alternativas; se estiver, propõe uma encomenda.” Cada passo é uma chamada a uma ferramenta e o agente compõe-nas. Com REST, o agente tem de codificar a forma do fluxo no próprio prompt.

#MCP e REST numa loja WooCommerce

Num projeto WooCommerce típico, traço a fronteira assim:

Os handlers das ferramentas do servidor MCP chamam os mesmos endpoints /wp-json/wc/v3/ que os consumidores REST usam. Uma única fonte de verdade para a camada de dados, duas superfícies para dois tipos de consumidor.

#Autenticação e scopes OAuth em MCP e REST

A autenticação em REST é terreno bem conhecido: tokens bearer, OAuth 2.x, basic auth em desenvolvimento. A convenção é “quem tem o token pode fazer tudo o que a documentação diz.” O afinamento dos scopes acontece por endpoint, ao nível da aplicação.

O MCP recorre às mesmas escolhas na camada de transporte, mas o SDK incentiva a associar scopes a cada ferramenta. Um único token OAuth pode transportar orders:read sem orders:write, e o servidor MCP impõe isso em cada chamada de ferramenta. Os padrões OpenAPI suportam a mesma ideia através de securityDefinitions e de segurança por operação, mas na prática a maioria das APIs REST documenta um único scope global e deixa a granularidade mais fina para a aplicação resolver.

Nas integrações com agentes, em particular, o mapeamento de scopes por ferramenta no MCP é um ganho ergonómico real, que também encaixa nos requisitos de minimização de dados do RGPD. O utilizador concede orders:read ao agente; o agente não consegue literalmente chamar order.cancel, porque o servidor MCP rejeita a chamada com forbidden antes de o handler correr. Por baixo, a autenticação é a mesma do REST, mas o contrato é mais legível tanto para o utilizador como para o agente.

#Em que difere a cache de respostas MCP da cache HTTP do REST?

O REST tem décadas de infraestrutura de cache HTTP: cabeçalhos Cache-Control, revalidação com ETag, regras Vary, cache na periferia da CDN, cache no navegador e em proxies intermédios. Uma resposta a GET /wp-json/wc/v3/products?stock_status=instock com Cache-Control: public, max-age=60 fica em cache na periferia sem esforço adicional.

O MCP não tem nada disto. As respostas das ferramentas viajam como payloads JSON-RPC dentro de pedidos POST. Os cabeçalhos de cache HTTP não se aplicam. A cache tem de acontecer ao nível da aplicação, dentro do handler da ferramenta, com uma chave explícita derivada da entrada. Isto funciona bem quando os próprios handlers do servidor MCP guardam em cache a chamada REST a montante (é o que faço em produção), mas significa que a camada de cache é um problema seu para desenhar.

Este é o argumento mais forte para manter o tráfego público de leitura em REST e encaminhar apenas o tráfego de agentes pelo MCP. A infraestrutura de cache HTTP é demasiado valiosa para abdicar dela na superfície pública.

#Como usar MCP e REST no mesmo backend WordPress

A arquitetura por defeito que entrego para sites WordPress e WooCommerce com ambições de agentes de IA:

                            ┌──────────────────┐
                            │  WordPress core  │
                            │   + WooCommerce  │
                            │   (REST origin)  │
                            └────────┬─────────┘
                                     │
                    ┌────────────────┼────────────────┐
                    │                │                │
            ┌───────▼────────┐  ┌────▼─────┐  ┌──────▼──────┐
            │  Public REST   │  │ Webhook  │  │ MCP server  │
            │ (cache at CDN) │  │ delivery │  │ (Workers)   │
            └───────┬────────┘  └────┬─────┘  └──────┬──────┘
                    │                │                │
            ┌───────▼────────┐  ┌────▼─────┐  ┌──────▼──────┐
            │ Storefront,    │  │ Partner  │  │  LLM agent  │
            │ price feeds,   │  │ endpoints│  │  (Claude,   │
            │ public APIs    │  │          │  │  ChatGPT,   │
            │                │  │          │  │  custom)    │
            └────────────────┘  └──────────┘  └─────────────┘

A mesma origem WordPress. Três superfícies, três perfis de consumidor. Os handlers do servidor MCP chamam os mesmos endpoints REST que a superfície pública guarda em cache; a entrega de webhooks partilha os mesmos hooks de eventos do WordPress que a lógica de invalidação do servidor MCP escuta.

A fronteira entre MCP e REST é uma decisão de implementação em produção, não uma decisão de código. A camada de dados (base de dados do WooCommerce, endpoints REST) é partilhada. A camada de apresentação (ferramentas tipadas contra recursos JSON) é separada.

#Erros comuns de arquitetura com MCP e REST

Pôr o MCP a fazer o trabalho do REST. Guardar em cache páginas públicas do catálogo através do MCP é um erro. Use REST com uma CDN.

Pôr o REST a fazer o trabalho do MCP. Documentar uma superfície de ações pensada para LLMs em OpenAPI e esperar que o agente “se desenrasque” dá resultados frágeis. Os agentes saem-se melhor com a descoberta de ferramentas do MCP.

Duas camadas de dados paralelas. Se os handlers MCP reimplementam a lógica de negócio em vez de chamarem a origem REST, cada atualização do WordPress parte as duas superfícies. Mantenha a camada de dados no WordPress e as superfícies de protocolo finas.

Esquecer o custo. Um servidor MCP é mais uma unidade a implementar, mais uma estratégia de autenticação, mais uma coisa a monitorizar. Não avance com um se o seu único consumidor for uma integração de ERP de um parceiro; publique o OpenAPI e dê o trabalho por concluído.

#Temas relacionados

Este artigo trata da decisão ao nível do protocolo. O passo a passo da implementação está em construir um servidor MCP para WooCommerce. A estratégia de autenticação está em padrões de autenticação MCP. O desenho de ferramentas tipadas está em ferramentas de catálogo tipadas com Zod para MCP. O caminho de migração a partir de uma API existente está em migrar uma API WordPress para MCP. A página do serviço é desenvolvimento de servidores MCP.

O preço é individual, porque a forma certa depende dos consumidores que serve e das ações que exigem contratos de nível de agente.