# MCP (Model Context Protocol) e Agent Skills (SKILL.md e AGENTS.md): guia completo para Claude Code, Cursor e Cloudflare
> Entenda o que é MCP (Model Context Protocol), a diferença entre servidores MCP, Agent Skills (SKILL.md) e AGENTS.md, e como conectar ferramentas seguras no Claude Code, Cursor e Cloudflare Workers.
**Autores:** Mauro Mequelussi
**Publicado:** 2026-11-10T16:04:54.568440721Z
**Atualizado:** 2026-11-13T03:37:30.71243668Z
**Tags:** claude-code, skills, mcp, agentes-de-ia, vibe-coding, cursor, agents-md
---
**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.

::callout{type="tip" title="Gere seu SKILL.md, AGENTS.md e .mcp.json agora"}
Use nosso **[Gerador e Validador Gratuito de SKILL.md, AGENTS.md e Servidor MCP](/ferramentas/gerador-mcp-skills)** para calcular o *Trigger Score* da sua skill, baixar o `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:

1. **Inspeciona o schema real do banco de dados** (por exemplo, lendo tabelas `SCHEMAFULL`, índices vetoriais HNSW e arestas de grafo no **SurrealDB**);
2. **Consulta logs e métricas de produção** (como Workers Logs, KV, R2 e traces no **Cloudflare** ou **Axiom**);
3. **Interage com o navegador ao vivo** (via **Chrome DevTools MCP** ou **WebMCP** `document.modelContext`) para auditar DOM, acessibilidade, cookies e requisições de rede;
4. **Calcula custos de arquitetura e consulta documentação verificada** (como o **Servidor MCP Público da Escola de Aplicativos**).

::video-player{src="https://www.youtube.com/watch?v=Vkcm5k7BtXw" title="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. |

::read-more{to="/blog/webmcp-sites-agentes-de-ia" title="WebMCP: como preparar seu site e suas ferramentas para agentes de IA no navegador"}
::

## 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:

1. **Nível 1 — Metadados no Frontmatter YAML (~50 a 100 palavras):** no início da conversa, o agente recebe apenas o `name` e a `description` de cada `SKILL.md`.
2. **Nível 2 — Corpo Principal do `SKILL.md` (< 500 linhas):** somente quando o pedido do usuário aciona a `description`, o agente lê o arquivo `SKILL.md` completo com as regras e o fluxo de trabalho.
3. **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:

::code-demo{title=".agents/skills/surrealdb-multimodel-rag/SKILL.md — Estrutura de alta ativação" lang="markdown"}
---
name: surrealdb-multimodel-rag
description: "Modela schemas SCHEMAFULL e escreve queries SurrealQL combinando tabelas, grafos (RELATE), busca textual BM25 e busca vetorial HNSW no SurrealDB. Use SEMPRE que o usuário mencionar SurrealDB, SurrealQL, memória de agentes, Graph RAG, migração do Supabase ou queries multi-modelo."
---

# surrealdb-multimodel-rag

## Guardrails Inegociáveis
- **Confine Record IDs externos:** Sempre valide com `assertRecordTable(id, 'tabela')` antes de `toRecordId()`.
- **Protocolo CBOR:** Passe `new Date()` (nunca string ISO) e `undefined` (nunca `null`) para campos `option<datetime>` em tabelas `SCHEMAFULL`.
- **Transações:** Envolva mutações com mais de uma escrita em `BEGIN TRANSACTION; ... COMMIT TRANSACTION;`.

## Fluxo de Execução
1. Verificar o schema existente antes de propor novas tabelas ou arestas.
2. Modelar relações ricas com `RELATE origem->aresta->destino` em vez de tabelas pivô manuais.
3. Unificar filtro relacional, travessia de grafo e similaridade vetorial (`<|k, ef|>`) em uma única query parametrizada.
::

::read-more{to="/cursos/claude-code-sem-misterio" title="Curso Gratuito: Claude Code sem Mistério (15 aulas práticas de CLAUDE.md, Skills e MCP)"}
::

## 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:

```bash
claude mcp add --transport http escola-aplicativos https://www.escoladeaplicativos.com.br/api/publico/mcp
```

### 2. 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:

::code-demo{title=".mcp.json — Configuração para projetos de produção" lang="json"}
{
  "mcpServers": {
    "escola-aplicativos": {
      "type": "http",
      "url": "https://www.escoladeaplicativos.com.br/api/publico/mcp"
    },
    "surrealdb": {
      "command": "npx",
      "args": ["-y", "@surrealdb/mcp-server"]
    },
    "cloudflare": {
      "command": "npx",
      "args": ["-y", "@cloudflare/mcp-server-cloudflare"]
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}
::

## 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):

::code-demo{title="Servidor MCP por requisição no Cloudflare Workers + Hono" lang="typescript"}
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: { name: 'meu-saas-mcp', version: '1.0.0' }
      }
    })
  }

  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)
})
::

::callout{type="warning" title="Segurança em Servidores MCP de Produção"}
Nunca exponha uma chave administrativa de banco de dados diretamente para um servidor MCP público. Sempre aplique autenticação baseada em sessão/RBAC (`requirePermissionHono`), valide todos os argumentos com **Zod** e adicione anotações `readOnlyHint` e `destructiveHint` em cada tool.
::

::read-more{to="/blog/hermes-agent-mcp-seguranca" title="Hermes Agent + MCP: como conectar ferramentas com menor privilégio e segurança"}
::

## Próximos passos: monte sua biblioteca de Skills e seu `AGENTS.md`

Para aplicar imediatamente no seu projeto:

1. Acesse o **[Gerador Gratuito de SKILL.md, AGENTS.md e Servidor MCP](/ferramentas/gerador-mcp-skills)** e gere a configuração exata da sua stack;
2. Assista gratuitamente aos cursos **[Claude Code sem Mistério](/cursos/claude-code-sem-misterio)**, **[Hermes Agent do Zero](/cursos/hermes-agent-do-zero)** e **[Mastra sem Mistério](/cursos/mastra-sem-misterio)**;
3. 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](/lp/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.