wppoland.com/mcp como servidor MCP ao vivo: arquitetura, integrações e casos de uso práticos para WordPress e comércio eletrónico

A forma mais rápida de compreender o que é realmente o Model Context Protocol (MCP) na prática não é ler extensas especificações teóricas nem examinar diapositivos gerados por computador. A forma mais rápida é enviar um único pedido para um URL ativo e funcional na web aberta:

https://wppoland.com/mcp

Nesse endereço funciona um servidor Model Context Protocol de produção no nosso site. Pode enviar pedidos POST com formato JSON-RPC 2.0. O servidor responde imediatamente com dados estruturados e tipados. Não requer nenhum plugin no painel de administração do WordPress, não precisa de chave de API, não tem custos e não realiza escritas na base de dados.

Se um assistente de IA (como o Claude Desktop, Claude Code, Cursor ou um agente autónomo de desenvolvimento) suporta MCP, pode consultar diretamente os nossos sistemas: Que serviços oferecemos realmente? Que tecnologias suportamos? Qual é o URL canónico para submeter um brief de projeto? O que o assistente não pode fazer é enviar um email em seu nome ou criar leads não verificadas no nosso CRM. Esta restrição é a base do nosso modelo de segurança de defesa em profundidade.

Neste guia aprofundado analisamos detalhadamente o funcionamento do endpoint MCP ao vivo em wppoland.com, a arquitetura do nosso servidor irmão de código aberto woocommerce-mcp, casos de uso empresarial reais para agências e lojas online, e lições aprendidas em produção na infraestrutura edge.

#Por que um servidor MCP direto muda as regras do jogo

As plataformas web tradicionais já dispõem de interfaces de programação. O WooCommerce inclui uma API REST madura. O WordPress disponibiliza /wp-json/ há muitos anos. O nosso próprio site publica um catálogo de serviços legível por máquinas em formato JSON sob /api/services.json.

Por que motivo, então, os assistentes de IA continuam a alucinar e a perder o contexto quando questionados sobre uma empresa numa janela de chat habitual?

Os grandes modelos de linguagem (LLM) operam através da previsão probabilística de sequências de texto. Quando um assistente tenta analisar um site através de extração de HTML ou dados de treino desatualizados, frequentemente inventa subpáginas inexistentes, assume serviços que nunca foram prestados ou fornece dados de contacto obsoletos.

O Model Context Protocol (publicado pela Anthropic em novembro de 2024 e gerido sob a Agentic AI Foundation da Linux Foundation; especificação: modelcontextprotocol.io) resolve este problema fundamentalmente. O MCP atua como um padrão universal - a porta USB para agentes de inteligência artificial.

Assim como um computador portátil não necessita de um driver específico para cada fabricante de teclado graças às portas USB normalizadas, um assistente de IA precisa de um protocolo uniforme para interagir com ferramentas externas. Uma ferramenta (Tool) no MCP é uma operação nomeada e determinística com um esquema JSON rigoroso para entradas e saídas.

Quando um cliente de IA suporta MCP, pode ligar-se a qualquer servidor compatível: um repositório de código, um gestor de tickets, uma base de dados de produtos ou um site de agência como o wppoland.com.

#Os três componentes em termos práticos

Uma arquitetura MCP é constituída por três elementos fundamentais:

1. O Cliente (Client): A aplicação com a qual o utilizador interage (Claude Desktop, Claude Code, Cursor IDE, Windsurf). Gere a janela de contexto, interpreta a intenção do utilizador e decide quando invocar uma ferramenta específica.
2. O Servidor (Server): Um programa leve ou função na edge (em wppoland.com, uma Cloudflare Pages Function) que publica o manifesto de ferramentas e executa os pedidos recebidos. O servidor não é o WordPress nem um plugin PHP.
3. A Ferramenta (Tool): Uma ação determinística única. No nosso endpoint público são disponibilizadas duas ferramentas: check_services e request_quote.

O fluxo de trabalho é direto: o cliente consulta as ferramentas disponíveis (tools/list), o modelo seleciona uma e valida os seus parâmetros, o servidor executa a lógica e devolve dados JSON estruturados, e o modelo formula uma resposta precisa para o utilizador.

#Interação passo a passo a partir do terminal

Pode testar o endpoint diretamente a partir do terminal com curl sem necessidade de escrever código de orquestração de IA:

curl -s -X POST https://wppoland.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A resposta devolve o manifesto com as ferramentas e os respetivos esquemas JSON Schema:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "check_services",
        "description": "List or search WPPoland services catalog with localized canonical URLs.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Optional search term to filter services"
            },
            "lang": {
              "type": "string",
              "enum": ["pl", "en", "de", "nb", "es", "pt-pt"],
              "description": "Target language for service titles and URLs"
            }
          }
        }
      },
      {
        "name": "request_quote",
        "description": "Get localized contact URL and brief submission instructions.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "project_type": {
              "type": "string",
              "description": "Type of project (e.g. mcp-server-development, woocommerce, audit)"
            },
            "lang": {
              "type": "string",
              "enum": ["pl", "en", "de", "nb", "es", "pt-pt"],
              "description": "Preferred language for the inquiry"
            }
          }
        }
      }
    ]
  }
}

Ao abrir https://wppoland.com/mcp no navegador, um pedido GET aponta para o cartão de descoberta:

https://wppoland.com/.well-known/mcp/server-card.json

#Configuração no Claude Desktop e Cursor

#Configuração para Claude Desktop

No ficheiro claude_desktop_config.json (no macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "wppoland": {
      "url": "https://wppoland.com/mcp/"
    }
  }
}

#Configuração para Cursor IDE

No ficheiro .cursor/mcp.json na raiz do projeto ou nas definições globais:

{
  "mcpServers": {
    "wppoland": {
      "url": "https://wppoland.com/mcp/"
    }
  }
}

Após reiniciar o assistente, pode perguntar: “Que serviços de otimização de WooCommerce e desenvolvimento de servidores MCP disponibiliza a WPPoland?”. O assistente invoca check_services com query: "woocommerce" e devolve links canónicos reais.

#Lição de produção: A barra final que quebrava 90% do tráfego

O JSON-RPC através de HTTP exige pedidos POST com corpo (body). Muitos servidores web e motores estáticos redirecionam automaticamente (301) caminhos sem barra final (/mcp) para caminhos com barra (/mcp/).

Muitos clientes automatizados falhavam perante isto:

• Algumas bibliotecas cancelavam a ligação imediatamente ao receberem um código 301.
• Outras seguiam o redirecionamento, mas convertiam o pedido num GET, descartando por completo o corpo do POST.

As nossas medições registaram 29 chamadas falhadas por dia contra apenas 2 com sucesso no caminho sem barra.

A solução: Uma regra de zona na Cloudflare que processa os pedidos POST para /mcp diretamente sem redirecionamento e devolve o estado HTTP 200. A taxa de sucesso subiu imediatamente para 100%.

#Arquitetura de segurança: Por que o só de leitura é inegociável

A ferramenta request_quote devolve informações estruturadas e precisas:

{
  "contact_url": "https://wppoland.com/pt-pt/contacto/?source=mcp",
  "method": "web-form",
  "note": "Endpoint só de leitura. Envie a mensagem através do formulário de contacto; esta ferramenta não envia emails automaticamente.",
  "suggested_message": "Pedido de orçamento: desenvolvimento de servidor MCP. Por favor incluir âmbito e stack tecnológico.",
  "reply_time": "no prazo de um dia útil"
}

Isto previne o abuso por spam e neutraliza ataques de injeção de prompts que tentem alterar estados em bases de dados.

#O homólogo para lojas: woocommerce-mcp

Para lojas WooCommerce, criámos e publicámos o pacote open-source:

https://github.com/wppoland/woocommerce-mcp

Disponível no npm como @wppoland/woocommerce-mcp (MIT, TypeScript), comunica diretamente com as APIs REST do WooCommerce utilizando chaves só de leitura, fornecendo cinco ferramentas:

• list_products: Pesquisa no catálogo por categoria e estado de stock.
• get_product: Obtenção de detalhes completos do produto por ID.
• list_orders: Consulta de encomendas recentes com filtros de estado (processing, on-hold).
• sales_report: Agregação de números de vendas e totais por períodos de datas.
• search_posts: Pesquisa em artigos de blog e base de conhecimento via WordPress REST API.

#Implementação em TypeScript com validação Zod

import { z } from "zod";

server.registerTool(
  "list_orders",
  {
    title: "List orders",
    description: "List recent WooCommerce orders, newest first. Optionally filter by status.",
    inputSchema: {
      per_page: z.number().int().min(1).max(100).optional(),
      status: z.enum([
        "any", "pending", "processing", "on-hold",
        "completed", "cancelled", "refunded", "failed"
      ]).optional(),
    },
  },
  async ({ per_page, status }) => {
    const cfg = loadConfig(true);
    const data = await wc(cfg, "orders", {
      per_page: per_page ?? 10,
      status,
      orderby: "date",
      order: "desc",
    });
    
    return ok(data.map((order) => ({
      id: order.id,
      number: order.number,
      status: order.status,
      total: order.total,
      currency: order.currency,
      date_created: order.date_created,
      item_count: order.line_items?.length ?? 0,
    })));
  },
);

#Chamadas detalhadas a ferramentas com cURL

Para compreender como funciona o método tools/call na prática, pode enviar um pedido direto ao servidor:

curl -s -X POST https://wppoland.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "check_services",
      "arguments": {
        "query": "mcp",
        "lang": "pt-pt"
      }
    }
  }'

O servidor processa o pedido e responde com o catálogo canónico de serviços:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Serviços encontrados (1):\n- Nome: Desenvolvimento de servidores MCP\n  ID: mcp-server-development\n  URL: https://wppoland.com/pt-pt/servicos/mcp-server-development/\n  Descrição: Desenvolvimento de servidores Model Context Protocol para WordPress e WooCommerce."
      }
    ]
  }
}

Da mesma forma, uma invocação de request_quote produz uma resposta estruturada sem qualquer escrita:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"contact_url\": \"https://wppoland.com/pt-pt/contacto/?source=mcp\",\n  \"method\": \"web-form\",\n  \"reply_time\": \"no prazo de um dia útil\"\n}"
      }
    ]
  }
}

#Quatro casos de uso práticos

#Caso de uso 1: Assistente operacional para e-commerce

Gestores de lojas online analisam automaticamente encomendas no estado on-hold e identificam faltas de stock sem terem de iniciar sessão no wp-admin.

Consulta em linguagem natural:

“Analisa as últimas 10 encomendas com estado on-hold. Calcula o valor total e identifica os produtos em falta.”

Cadeia interna de ferramentas:

1. O assistente invoca list_orders(status="on-hold", per_page=10).
2. O servidor MCP devolve identificadores e montantes sem dados PII.
3. Para os artigos relevantes invoca get_product(id=...).
4. O assistente sintetiza uma tabela de resumo clara.

#Caso de uso 2: Triagem de consultas B2B para agências

Agentes de IA de potenciais clientes consultam especializações técnicas via check_services e obtêm links de contacto canónicos.

#Caso de uso 3: Suporte ao cliente de primeiro nível

A equipa de helpdesk consulta stock e variantes de produto através de um bot de Slack ligado ao MCP.

#Caso de uso 4: Orquestração de conteúdo em WordPress Headless

Redatores verificam temas existentes com search_posts antes de escreverem novos artigos para prevenir canibalização de SEO.

#Comparação técnica: stdio vs. Streamable HTTP vs. SSE

#Conclusão

Tornar o WordPress e o WooCommerce acessíveis a agentes de IA através do wppoland.com/mcp e do woocommerce-mcp no GitHub é viável de forma segura, escalável e sem sobrecarregar o servidor.

Consulte os nossos serviços de desenvolvimento de servidores MCP para WordPress ou teste o endpoint diretamente a partir do seu terminal.