MCP (Model Context Protocol) e Agent Skills (SKILL.md e AGENTS.md) formam a arquitetura padrão de engenharia de contexto em 2026 para transformar agentes de código como Claude Code, Cursor, Google Antigravity, Codex e Hermes Agent em engenheiros de software previsíveis. Enquanto o AGENTS.md define as regras permanentes do repositório e as Agent Skills (SKILL.md) ensinam procedimentos sob demanda (Progressive Disclosure), o servidor MCP conecta o agente a bancos de dados, APIs e ferramentas em tempo real.
Se você já tentou fazer Vibe Coding em um projeto real e percebeu que a IA esquece as convenções do projeto, inventa tabelas que não existem no banco ou erra a sintaxe de bibliotecas recentes, o problema raramente está no modelo. O problema está na falta dessas três camadas trabalhando juntas.
AGENTS.md da sua stack e conectar o servidor MCP público da Escola de Aplicativos em segundos.O que é MCP (Model Context Protocol) e por que ele mudou o desenvolvimento com IA
O Model Context Protocol (MCP) é um protocolo aberto baseado em JSON-RPC 2.0 que padroniza como modelos de linguagem (LLMs) e agentes autônomos descobrem recursos (Resources), prompts padronizados (Prompts) e executam ferramentas (Tools) em sistemas externos.
Antes do MCP, cada integração exigia colar dezenas de páginas de documentação ou resultados de queries manualmente no chat. Com um servidor MCP conectado à sua IDE (via transporte local stdio ou remoto Streamable HTTP), o próprio agente:
- Inspeciona o schema real do banco de dados (por exemplo, lendo tabelas
SCHEMAFULL, índices vetoriais HNSW e arestas de grafo no SurrealDB); - Consulta logs e métricas de produção (como Workers Logs, KV, R2 e traces no Cloudflare ou Axiom);
- Interage com o navegador ao vivo (via Chrome DevTools MCP ou WebMCP
document.modelContext) para auditar DOM, acessibilidade, cookies e requisições de rede; - Calcula custos de arquitetura e consulta documentação verificada (como o Servidor MCP Público da Escola de Aplicativos).
Engenharia Reversa e Agentes de Código com Claude Code e MCP na Prática
Diferença entre MCP, Agent Skills (SKILL.md) e AGENTS.md (CLAUDE.md)
A dúvida mais comum entre desenvolvedores que usam Claude Skills, Cursor Rules e MCP Servers é saber quando usar cada um. Misturar tudo em um único arquivo gigante estoura a janela de contexto, encarece o consumo de tokens e reduz a precisão do modelo.
Veja a divisão arquitetural correta:
| Camada | Arquivo / Protocolo | Quando é carregado no contexto? | Função principal na engenharia com IA |
|---|---|---|---|
| 1. Regras Globais do Repositório | AGENTS.md / CLAUDE.md | Sempre (no início de toda sessão) | Comandos de build/test (pnpm turbo), mapa do monorepo e guardrails inegociáveis de segurança. |
| 2. Conhecimento Procedural (Skills) | .agents/skills/<nome>/SKILL.md | Sob demanda (Progressive Disclosure) | Passo a passo especializado (ex.: como integrar Pagar.me V5, configurar webhooks da Meta ou escrever SurrealQL). |
| 3. Ação e Dados ao Vivo (MCP) | .mcp.json (stdio / http) | Apenas na chamada da Tool | Executar queries reais, ler schemas do banco, buscar documentação atualizada e operar serviços externos. |
| 4. Ação no Navegador (WebMCP) | document.modelContext | Ao abrir a página web no Chrome | Permitir que agentes de navegador operem interfaces web como ferramentas tipadas, sem depender de cliques frágeis em coordenadas. |
Como funcionam as Agent Skills (SKILL.md) e o segredo do Progressive Disclosure
Uma Agent Skill não é um simples prompt salvo. Ela usa um sistema de carregamento em três níveis (Progressive Disclosure) que permite instalar 50 ou 100 skills no projeto sem desperdiçar a janela de contexto do modelo:
- Nível 1 — Metadados no Frontmatter YAML (~50 a 100 palavras): no início da conversa, o agente recebe apenas o
namee adescriptionde cadaSKILL.md. - Nível 2 — Corpo Principal do
SKILL.md(< 500 linhas): somente quando o pedido do usuário aciona adescription, o agente lê o arquivoSKILL.mdcompleto com as regras e o fluxo de trabalho. - Nível 3 — Recursos Empacotados (
references/,scripts/,examples/): arquivos auxiliares pesados só são lidos se o passo específico exigir.
Por que muitas Skills falham ao ativar (e como corrigir o Frontmatter)
Agentes como o Claude Code e o Cursor tendem a sub-ativar (undertrigger) skills quando a description do frontmatter é passiva (por exemplo: "Guia sobre como usar o SurrealDB"). Para garantir ativação confiável, toda informação de "quando usar" deve estar dentro do campo description no YAML, nunca apenas no corpo do Markdown:
surrealdb-multimodel-rag
Guardrails Inegociáveis
- Confine Record IDs externos: Sempre valide com
assertRecordTable(id, 'tabela')antes detoRecordId(). - Protocolo CBOR: Passe
new Date()(nunca string ISO) eundefined(nuncanull) para camposoption<datetime>em tabelasSCHEMAFULL. - Transações: Envolva mutações com mais de uma escrita em
BEGIN TRANSACTION; ... COMMIT TRANSACTION;.
Fluxo de Execução
- Verificar o schema existente antes de propor novas tabelas ou arestas.
- Modelar relações ricas com
RELATE origem->aresta->destinoem vez de tabelas pivô manuais. - Unificar filtro relacional, travessia de grafo e similaridade vetorial (
<|k, ef|>) em uma única query parametrizada.
Como conectar o Servidor MCP Público da Escola de Aplicativos na sua IDE
Para demonstrar o padrão MCP Streamable HTTP rodando na borda do Cloudflare Workers, disponibilizamos um servidor MCP público e gratuito em https://www.escoladeaplicativos.com.br/api/publico/mcp.
Ao conectá-lo no seu Claude Code, Cursor ou Antigravity, seu agente ganha ferramentas nativas (ea_search_catalog, ea_simulate_supabase_vs_cloudflare, ea_simulate_whatsapp_official_api, ea_simulate_cloudflare_r2_vs_s3, ea_simulate_hotmart_kiwify_fees e ea_calculate_instagram_engagement) para consultar nossos guias em Markdown e calcular custos de infraestrutura sem sair do código.
1. Adicionar com 1 comando no Claude Code CLI
No terminal do seu projeto, execute:
claude mcp add --transport http escola-aplicativos https://www.escoladeaplicativos.com.br/api/publico/mcp2. Configurar via .mcp.json no Cursor, Antigravity ou Claude Code
Salve o arquivo .mcp.json na raiz do seu repositório combinando o MCP da Escola de Aplicativos com os servidores do SurrealDB, Cloudflare e Chrome DevTools:
Como criar seu próprio Servidor MCP Stateless no Cloudflare Workers
Quando você constrói um SaaS ou ecossistema digital, expor um servidor MCP próprio permite que agentes internos (como o Hermes Agent) ou clientes autorizados operem seu produto com segurança.
Em ambientes serverless como o Cloudflare Workers, a melhor prática da especificação MCP é usar o transporte Streamable HTTP Stateless e instanciar o servidor por requisição (nunca guardando estado de sessão em variáveis globais de módulo Worker, o que violaria o isolamento entre requisições):
import { Hono } from 'hono'
const app = new Hono()
app.post('/api/publico/mcp', async (c) => { const body = await c.req.json() const { id, method, params } = body
if (method === 'initialize') { return c.json({ jsonrpc: '2.0', id, result: { protocolVersion: '2025-03-26', capabilities: { tools: { listChanged: false } }, serverInfo: } }) }
if (method === 'tools/list') { return c.json({ jsonrpc: '2.0', id, result: { tools: { name: 'consultar_metricas_produto', description: 'Retorna métricas consolidadas do tenant autenticado.', annotations: { readOnlyHint: true }, inputSchema: { type: 'object', properties: { periodoDias: { type: 'number' } }, required: 'periodoDias' } } } }) }
return c.json({ jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } }, 404) })
requirePermissionHono), valide todos os argumentos com Zod e adicione anotações readOnlyHint e destructiveHint em cada tool.Próximos passos: monte sua biblioteca de Skills e seu AGENTS.md
Para aplicar imediatamente no seu projeto:
- Acesse o Gerador Gratuito de SKILL.md, AGENTS.md e Servidor MCP e gere a configuração exata da sua stack;
- Assista gratuitamente aos cursos Claude Code sem Mistério, Hermes Agent do Zero e Mastra sem Mistério;
- Se você quer implementar essa arquitetura completa (checkout próprio, CRM, WhatsApp oficial, área de membros e agentes MCP) no seu negócio com acompanhamento individual, conheça a Mentoria Ecosystem.
Perguntas frequentes
O que significa MCP na Inteligência Artificial?
MCP significa Model Context Protocol (Protocolo de Contexto de Modelo). É um padrão aberto baseado em JSON-RPC 2.0 criado para conectar modelos de IA e agentes de código (como Claude Code, Cursor, Antigravity e Hermes Agent) a fontes de dados externas, bancos de dados e ferramentas sem precisar de integrações proprietárias para cada modelo.
Qual a diferença entre Claude Skills (SKILL.md) e AGENTS.md?
O arquivo AGENTS.md (ou CLAUDE.md) fica na raiz do repositório e é carregado integralmente em todas as sessões para informar comandos de build, estrutura de pastas e regras globais. Já uma Agent Skill (SKILL.md) fica em .agents/skills/<nome>/SKILL.md e usa carregamento progressivo (Progressive Disclosure): o agente lê apenas o resumo no início e só carrega o manual completo quando a tarefa exige aquela especialidade.
Como usar MCP no Claude Code e no Cursor gratuitamente?
No Claude Code, você pode registrar qualquer servidor MCP remoto via terminal com claude mcp add --transport http <nome> <url> (por exemplo, claude mcp add --transport http escola-aplicativos https://www.escoladeaplicativos.com.br/api/publico/mcp) ou criar um arquivo .mcp.json na raiz do projeto, que também é reconhecido nativamente pelo Cursor e pelo Google Antigravity.
É seguro conectar o banco de dados de produção via MCP no Lovable ou Cursor?
Conectar credenciais de superusuário do banco de produção diretamente ao cliente de IA é um risco grave de segurança. Em desenvolvimento local ou staging, use bancos isolados com permissões mínimas; para operações em produção, exponha apenas tools de negócio validadas com Zod e protegidas por RBAC através de um servidor MCP em Cloudflare Workers.