RAG e MCP, na prática. Cole o prompt e monte os dois

Imagina um estagiário novo. Alguém pergunta "qual o TTL do cache de idempotência?". Ele pode: (a) chutar, (b) perguntar pro colega do lado, (c) ir na pasta certa e puxar o runbook. O modelo faz o mesmo. Sem a pasta certa, chuta. Com a pasta errada, cita confiante o número de janeiro.

Esse estagiário com a pasta certa é RAG. O crachá que deixa ele entrar em qualquer sistema da empresa é MCP. E o curso de comunicação que muda o jeito dele responder — não o que ele sabe — é fine-tuning.

Pouca gente tem os três no harness. Menos ainda sabe qual é qual.

Na prática: você pergunta o TTL do cache de idempotência. O agente lê o runbook: 60s, a janela. Você abre o código: 120. Ele não alucinou. O doc documenta a janela. O TTL nunca esteve no índice. Colar a nota no chat também não resolve.

O modelo não ficou mais esperto. Ele só prevê a próxima palavra com o que está no contexto agora. RAG colocou a janela nesse contexto. Sem o trecho, ele chuta. Com o runbook pela metade, cita certo o número que estava lá: 60. A pergunta era 120. Fine-tuning não coloca o TTL nos pesos. Muda o jeito da frase, se o fato já estiver no turno.

Como o trecho chega neste desk:

pergunta → harness → MCP → RAG busca o doc → contexto → resposta

MCP no meio não porque MCP "é pedir trecho". MCP é protocolo: tool, resource, API, arquivo, banco. Neste fluxo a busca entra como tool. Fine-tuning fica fora do caminho.

O que você leva daqui: cole o prompt e monte os dois. RAG busca o doc. MCP conecta o harness ao que o servidor expõe. Fine-tuning muda o jeito. Se a primeira ferramenta do último chat não casa com a camada, você ainda está na teoria.

Camada	Papel	No desk
RAG	Busca o doc	Logseq, Notion, Confluence. Devolve o trecho certo.
MCP	Protocolo	Tool, resource, API, arquivo, banco. Neste fluxo: o harness alcança a busca por ele. Um host, duas tools: function calling nativo resolve.
Fine-tuning	Muda o jeito	Não guarda o doc. Só o padrão da resposta. Fora do runtime da pergunta.

Neste desk: monta a busca, depois o conector até ela. Se o formato ainda vazar, aí sim fine-tuning muda o jeito.

Depois de montar, o fato que faltava entra no doc. TTL 120: uma linha no runbook e no índice. A próxima pergunta pega o 120. O modelo não retreina. Se o código mudou e o runbook não, volta a mesma pergunta: retrieve certo, índice pela metade. MCP muda o conector, não o corpus. Fine-tuning não recebe o 120. Só entra de novo se o jeito mudou, e ainda assim depois de prompt e schema.

O erro é pular etapa. Colar a nota no chat não é MCP. Um conector que além de buscar também grava, sem gente no meio, vira incidente.

Abaixo: quatro perguntas. Se o último chat já responde, pode parar. Quem monta segue no prompt.

Tabela de Conteúdo

• 1. Nomeia o problema antes da ferramenta
• 2. RAG: busca o doc, não o peso
• 3. MCP: protocolo, não a busca
• 4. Fine-tuning: muda o jeito, não o catálogo
• 5. Cole isto no seu agente
• 6. Context window grande não é desculpa pra jogar o repositório inteiro
• 7. Não use o mesmo modelo (LLM) para tudo
• 8. O modelo é o mesmo. O harness muda
• 9. Se for implementar RAG, MCP ou fine-tuning de verdade, lê isto depois

1. Nomeia o problema antes da ferramenta

Antes de ligar mais uma ferramenta, pergunta:

1. Você precisa de um texto que já existe (política no Notion, ADR, README, o retry da API) e só quer o trecho certo? Isso muda em dias. É RAG. O harness alcança essa busca por MCP ou por function calling. Ou você precisa do agora: o pipeline passou, o PR está aberto, o teste quebrou, o banco tem o registro? Isso não é RAG. Está no CI, no git, no banco: outra tool, no mesmo protocolo ou nativo.
2. Se o agente errar, o pior é uma frase ruim no chat, ou ele pode gravar de verdade: merge, apagar arquivo, disparar pagamento, fazer deploy? Consultar e gravar podem ir no mesmo conector. Gravar precisa de gente no meio.
3. O trecho certo já está na conversa (você vê o arquivo, a regra, o JSON) e o que sai torto é só o formato: mistura finding com palpite, tom errado, label errada? Aí não falta fato. Falta jeito. Fine-tuning, depois de prompt e schema.
4. Vocês estão colando o repositório inteiro no chat para achar dois arquivos? Isso não é busca. É dump. Janela grande não acha o handler. Acha o meio.

Se o time grita fine-tuning e o fato nem entrou na conversa, vocês estão no item 1 fingindo que é o 4.

Quem constrói confere no histórico da conversa. Qual foi a primeira ferramenta que o agente usou nesta rodada? A tabela abaixo é o mesmo diagnóstico, em código.

O que você perguntou	Primeiro tool caro	Primeiro tool barato
Timeout, retry, contrato deste serviço	Busca no README de janeiro	Read do código agora. Reindex se o doc mentir.
O pipeline da main passou?	XML / JUnit no vetor	gh run agora
Quem chama este handler?	Dez Read "só pra garantir"	Mapa (grafo / LSP), depois 1–2 arquivos
JSON do review mistura finding e palpite	LoRA no OpenAPI	Schema no prompt. Finding ≠ hipótese.

Abre o último chat. O de ontem, não o demo. Primeira ferramenta: busca no doc, Read/gh, algo que grava, ou "vamos treinar"? Se não foi o barato da tabela, a camada estava errada.

Duas perguntas que eu fiz no chat. Histórico anonimizado. A primeira ferramenta foi busca no vault, via MCP, nas duas. O que muda é o índice.

Número de negócio. Doc e código bateram.

você:     qual é a janela de idempotência neste serviço?
primeira: MCP read no vault  (hub)
depois:   MCP read  (runbook.md → 60s, ADR datado)
          grep      (middleware.php → 60)
doc:      60s
código:   60s
camada:   índice vivo

Detalhe de implementação. O runbook documenta a janela. Não o TTL do cache. Grep no vault: vazio. O número estava no código.

você:     qual é o TTL do cache de idempotência?
primeira: MCP read no vault  (hub)
depois:   MCP read  (runbook.md → 60s, janela)
          grep no vault  (nada sobre TTL)
          Read  (middleware.php → 120)
doc:      vazio no TTL
código:   120s
camada:   índice pela metade

O vault não mentiu. Documentou o fato de negócio. Quem debuga "por que a chave ainda está no cache depois da janela?" não acha resposta no índice. Vai pro Read. A correção é uma linha no runbook, não LoRA. Dez Read vs mapa: a diferença está no primeiro tool do transcript.

Cartão + prompt: Antes de ligar RAG, MCP ou LoRA: vê a primeira ferramenta que o agente usou.

2. RAG: busca o doc, não o peso

Logseq, Notion, Confluence, o runbook. Mesma conta da abertura: o fato está no doc. RAG busca o trecho. Não treina o doc de novo.

Isso mora no ADR, no runbook, no comentário do handler. Não mora no gh pr view de agora. Busca a regra no doc. Consulta o PR aberto na ferramenta. Inverter é inventar política ou procurar ADR na API do GitHub.

A janela estava no runbook. O TTL, não. Fine-tuning não escreve essa linha. Tool de GitHub também não. Se o fato mudou, você fornece o fato agora, na fonte. Treinar de novo é o caminho rígido e caro pra número que vive no runbook.

O modelo sabe HTTP. Não sabe o contrato deste serviço, a não ser que o trecho esteja no turno. RAG é a busca na pergunta, com fonte. Não é treinar de novo cada vez que o time muda o retry.

O que RAG não é: o status do Actions agora. Se muda a cada push, o índice mente educado.

O que você ganha: fato que atualiza sem treinar de novo, e dá pra apontar o arquivo. No trabalho: o modelo busca menos pra fora. Decide no contexto do time.
O que você paga: alguém tem que cuidar da base. Nota de janeiro no índice, política de março no jurídico: citação bonita, regra morta.

O doc ainda não chegou no harness. Isso é o próximo passo.

3. MCP: protocolo, não a busca

MCP não é a busca. É o protocolo: tool, resource, API, arquivo, banco. O harness chama o que o servidor expõe.

O fluxo da abertura é uma composição, não a definição. MCP no meio não porque "MCP pede trecho" seja o que MCP é. Porque neste desk a busca entra como tool.

O Logseq não anda sozinho até o chat. Sem conector, você cola a nota. Com o conector, a tool de retrieve entra no turno. RAG continua sendo a busca. MCP, neste desk, é como o harness chega nela.

Se o servidor está verde e o transcript ainda começa em dez Read, você não ligou o RAG. Só instalou o protocolo.

Um host, duas tools? Function calling nativo resolve. MCP começa a valer quando a mesma busca precisa aparecer em mais de um IDE, ou quando o time não quer reinventar o conector a cada harness.

O mesmo servidor pode expor outra coisa: git, CI, banco, pagamento. Isso não vira RAG. Leitura da busca ≠ push. HITL no que grava. Sem isso, o servidor "só de busca" vira force push. A sessão que consulta o manual não é a sessão que dispara o pagamento.

O que você ganha: o harness chega no doc (Logseq, Notion, Confluence) sem colar a nota no chat. E, se precisar, chega em sistema vivo pelo mesmo protocolo, em outro cano.
O que você paga: superfície. Cada tool a mais no mesmo servidor é um jeito de errar no mundo real.

4. Fine-tuning: muda o jeito, não o catálogo

Aqui o fine-tuning muda o jeito. Não busca o doc. Se a busca já devolve o trecho certo (RAG) e o harness já alcança essa busca (MCP ou function calling), e mesmo assim o formato vaza, aí conversa treino.

Fine-tuning não é o próximo passo porque o hype pediu. Prompt e schema são o degrau do meio. Treino é o último. Ele muda como o modelo responde: estilo, formato, padrão que se repete. Não é o jeito de ensinar as 400 rotas da API.

Um limite só: eu não treinei um modelo grande neste laboratório. O passo barato que eu uso é schema no prompt. Finding, observação e hipótese em campos separados. Sem arquivo:linha não é finding. Fine-tuning seria treinar esse jeito, mil vezes, se o schema não segurasse. Não seria gravar o OpenAPI nos pesos.

"Vamos treinar com o OpenAPI inteiro"

Amanhã o endpoint muda. O modelo, não. O spec de terça ficou preso nos pesos. Cena pedagógica:

você:     qual o path de cancelamento?
agente:   POST /v1/subscriptions/cancel  (spec de junho)
código:   POST /v2/billing/cancel        (desde agosto)
alguém:   "alucinou"

Não alucinou. Você pediu pra ele lembrar rota. Rota é fato. Fato vai pra busca no spec, ou pra tool que lê o OpenAPI no repo. Nunca pro peso, se muda.

Indexar o código-fonte no dataset de treino é o mesmo erro. O time muda o handler. Você ficou com um Readme.bak caro, que não dá grep.

O JSON do review sai torto

O arquivo certo já está no contexto. O modelo mistura "acho que é CSRF" com finding, quebra o JSON, escreve como blog.

Aí pode ser comportamento. Ainda não é abrir o painel de treino.

Ordem: prompt claro, dois exemplos bons, schema. Finding só com arquivo:linha. Hipótese em outro campo.

Se depois disso o formato ainda vaza em mil reviews por dia, aí sim: exemplos do jeito certo de reportar. Não o repositório no JSONL.

Quando fine-tuning vale

Classificar issue o dia inteiro: bug, dívida, feature. O rótulo quase não muda. Um modelo menor sai mais barato que o modelo caro lendo prosa.

Tom do time no review em escala, sem system prompt de oito mil tokens. O conteúdo (qual handler, qual timeout) continua de fora: busca ou tool.

"Não gera PoC, não abre PR nesta sessão" automático, quando o prompt já não segura.

Regra: se a correção é "atualiza o README", não é fine-tuning. Se ele viu o código e mesmo assim escreve o review errado do mesmo jeito, mil vezes, aí conversa.

5. Cole isto no seu agente

Isto não é receita de instalar RAG, MCP e LoRA. É o contrato das camadas, pra colar numa conversa nova. Se você não tem nada, o agente monta a semana 1 do jeito certo: README do repo, tools nativas, fine-tuning depois. Arquiteto, não gerador de código. O bloco é longo de propósito.

Conversa nova. Cinco linhas do seu repo. Ele vasculha o que você colou (e o README/docs/MCP do tree, se o IDE deixar). Só então escolhe: 3 perguntas, 8, ou já o plano. Sem stack: default e semana 1. Stack complexa: até 8, aí espera. Não manda já commitar.

Se devolver "vamos treinar o OpenAPI" ou "um MCP com as 40 APIs", você pulou as perguntas. Manda o trecho no comentário.

Antes de ligar RAG, MCP ou LoRA: vê a primeira ferramenta que o agente usou (prompt + cartão):

You are an architect, not a code generator.

I am designing an agentic setup for a software team. I may paste repo context, a stack description, or a messy Slack thread. Do not assume Cursor, Claude, Copilot, or any other host. Talk in terms of layers.

Do not write application code in the first reply. Do not invent tools, datasets, or vendors I did not mention.

First pass, before any questionnaire: inspect what I pasted. If the harness can see the repo, look only at README, docs/ (or where docs are pointed), connector/MCP config, any existing index. A handful of Reads. Not ten. Not dump. Cite what you found. Then classify from that evidence: nothing vs complex. Do not pick 3 or 8 before this pass.

If the pass shows nothing (no RAG, no MCP, no LoRA): ask at most 3 short questions: (1) where do docs live today, (2) one IDE or several, (3) does anything need to write (push, pay, deploy). If I skip them or say I have nothing, assume: corpus = README/ADR in the repo; one host; native function calling (no MCP yet); fine-tune = not now; do not dump the repo. Then output the sections below in this same reply. Week-1 bullets must be doable with only that repo and that IDE. They are the first correct setup, not a shopping list.

If the pass already has enough, skip questions and output. If the pass shows a complex stack (several hosts, writes, existing MCP, index, or I proposed fine-tuning) and something material is still missing, ask up to 8 short questions, then stop and wait. The 8 are for that case. Not for the nothing-case.

Mental model (non-negotiable):
- This stack does not make the model smarter. It is harness discipline: directed context at query time, so next-token prediction is better grounded. At work, retrieve in-corpus first: less fishing on the public web, fewer exploratory Reads. Tokens drop vs dump or ten Reads, not vs an empty chat.
- RAG / retrieval = the knowledge base (Logseq, Notion, Confluence, ADRs, READMEs) plus search at query time. Cite sources. Not a substitute for live CI, git, or DB.
- MCP = a protocol (tools, resources, APIs, files, DBs). Not the corpus. Not RAG. This article's happy path is a composition: the harness reaches retrieval through MCP, or through native function calling. Native function calling is enough if I have one host and two tools.
- Tools that mutate (push, pay, email) may ride the same connector. They are not RAG. Read ≠ write. HITL on writes.
- Fine-tuning = behavior (format, tone, labels) AFTER retrieval is reachable and facts are right. Try system prompt, few-shot, and strict JSON schema first. Never fine-tune to inject an OpenAPI spec, a codebase, or API paths that change.
- Context budget = do not dump the monorepo. Prefer a code map / graph / LSP query, then 1–2 files. A large context window still loses the middle.
- Model role = pick by trained skill and claimed capability, not the IDE logo. The turn only tells you which of those skills you need now: daily craft, hard architecture, code review, security review.

Also respect:
- Least privilege: read tools ≠ write tools. git push, merge, migrate, deploy need a human in the loop. No unbounded shell "to make the demo work".
- Exposing remember()/recall() as a tool does not make a memory policy.
- Exposing RAG as one MCP tool is allowed, but the agent must still know WHEN to search docs vs WHEN to call git/CI.

After you have enough answers, output exactly these sections in my language (pt-BR unless I write in English):

1. Diagnosis — for MY repo/workflow, what is knowledge vs action vs behavior vs budget vs model role. One paragraph.
2. RAG — what corpus (docs vs code), what must NEVER go in the index, how we know a hit is stale vs the tree.
3. MCP / protocol — what the harness can call. Table: server, what it exposes (retrieve vs git vs mutate), blast radius, HITL, MCP vs native function calling and why. If I treated MCP as a synonym of RAG, or as "the thing that asks for the snippet", correct me: that is a composition, not the definition.
4. Fine-tune — "not now" or a precise behavior to learn, with the prompt/schema alternative we will try first. If I proposed fine-tuning OpenAPI or the repo, refuse and reroute to RAG or a tool that reads the spec from git.
5. Context budget — dump vs map. One indexer max.
6. Model posts — map daily craft / hard architecture / code review / security review onto models by trained skill and claimed capability, using whatever I already pay for. If I named none, propose the jobs without vendor lock-in.
7. Week-1 plan — 5 bullets I can do in the repo without buying a new course. No new logo unless I already have it. If I had nothing, these bullets are how I mount week 1 the right way.

End with 3 risks if I ignore the diagnosis.

O prompt já dá pra colar. As duas seções seguintes não são RAG nem MCP. São o que ainda quebra na prática: jogar o repo no context window, e trocar de modelo achando que montou camada.

6. Context window grande não é desculpa pra jogar o repositório inteiro

"O context window é enorme, manda o monorepo."

Você não economizou. Enterrou o handler certo no meio.

Na prática (cena pedagógica):

você:     quem chama applyTimeout neste serviço?
dump:     monorepo no context window
agente:   cita vendor/retry/README.md
          "30s, 3 tentativas"  (achou o que parecia)
mapa:     applyTimeout ← PaymentHttpClient ← WebhookController
código:   src/http/client.ts, 5s, um caller

O modelo citou. Citou o arquivo errado. Context window grande entrega o meio. Não o handler.

Indexar o repo no vetor e chamar de RAG também não resolve. Mapa responde quem chama. Vetor de 40 mil chunks responde parece com. Se o histórico começa em dez Read, não tem mágica. Tem pasta no disco.

7. Não use o mesmo modelo (LLM) para tudo

Isso não é a quarta camada. É o seletor. Trocar o logo não busca o doc, não conecta o harness e não muda o jeito.

"Arruma o auth."

Pode ser typo no middleware. Um if, um import, o token caiu no header errado. Um arquivo. Coding no fluxo. O modelo que se propõe a isso resolve e segue.

Pode ser recorte de seis módulos. Gateway, sessão, cookie, refresh, o middleware que ainda deixa passar o path antigo. Vira desenho. ADR. Troca de contrato. Vários arquivos, horizonte longo. O pedido é o mesmo. O skill não é.

Pode ser code review. O patch passou. Quem implementou quer terminar. Quem revisa quer discordar. Isso pede o teto, não o modelo que acabou de escrever o diff.

Pode ser security review no source. O furo de autorização ficou no PR. Não é pentest. É ler o diff contra o contrato de auth.

O texto do pedido sozinho não separa. "Arruma o auth" não diz se você precisa de um patch, de um recorte ou de um review. Quem escolhe modelo sem isso cola o skill errado no seletor.

Não escolhe pela IDE. Escolhe pelo skill / capability que o modelo declara. Sem ranking. Não rodei o leaderboard deles.

Skill / capability	Vendor
Coding in the loop, ship	Grok 4.6 High: coding, agentic, knowledge work
Multi-file recorte, ADR	Claude Opus 5: complex agentic coding, long refactor
Code review	Claude Fable 5: highest capability, long SWE
Security review (source)	Claude Fable 5: Mythos-class. Cyber no GA, com safeguard

O modelo do dia a dia revisando o diff de auth é viés do próprio patch. Quem escreveu o patch não é quem caça o furo. Fable no seletor é o teto GA: Mythos-class com safeguard. Mythos 5 é o mesmo peso, acesso restrito. Code review e security review de source no PR. Não é pentest.

Trocar de modelo não substitui RAG, MCP ou fine-tuning. Fine-tuning não substitui o README que faltava.

8. O modelo é o mesmo. O harness muda

Não ganhamos um modelo mais inteligente. Ganhamos um harness que para de chute: o trecho certo entra no turno, o context window não vira dump. Predição mais acertada. O cérebro é o mesmo.

No trabalho isso pesa. A política já está no doc. O modelo para de completar com o treino público, para de abrir dez arquivos "só pra garantir". Token cai quando a alternativa era dump ou dez Read. Retrieve ainda gasta contexto. Gasta o certo.

O que ganhamos não é "ter RAG, MCP e LoRA" no vocabulário. É ter busca, protocolo e jeito no harness, cada um no papel certo. Página velha não se resolve treinando. Colar no chat não é protocolo. Trocar o logo no seletor não atualiza o README.

Dá pra usar no Kiro, no Cursor, no Claude Code, no Codex. A conta não é do logo. Knowledge base, conector, jeito, context window: isso mora no harness que você estiver. Um host, duas tools: function calling nativo resolve. Vários hosts, a mesma base: aí o MCP vale, pra não reinventar o conector em cada um. O histórico da primeira ferramenta funciona em todos. Se o primeiro movimento muda quando você troca de IDE, você não montou camada. Montou atalho daquele app.

9. Se for implementar RAG, MCP ou fine-tuning de verdade, lê isto depois

Até aqui a gente só fechou a conta: o que é cada camada, o que não é, o que olhar no histórico. Chunk, servidor MCP, memória entre sessões, mapa do repo: isso não cabia neste texto. Se você for implementar isso no IDE, esses quatro links são o próximo passo. Na ordem. Cada um cobre uma coisa que eu deixei de fora de propósito.

1. Mesmo com GraphRAG, o agent se perde sem contrato de memória. Retrieve não é memória. Hub, o que gravar, o que não.
2. MCP: intro oficial. Host, client, server. Tools e resources. Como o protocolo existe de fato.
3. Contextual retrieval (Anthropic). Chunk, embedding, o que a busca devolve quando o índice é mais do que "joga no vetor".
4. Fine-tuning (OpenAI). Quando é comportamento. Quando não é fato. Dataset, não OpenAPI nos pesos.

Os quatro links são o passo seguinte, se for montar de verdade. O que este texto pede é não pular a camada. O prompt + cartão não instala a stack. Diagnostica a sua. Cola no Kiro, no Cursor, no Claude Code, no Codex.

No seu último chat: a primeira ferramenta foi a busca do RAG (MCP ou function calling), outra tool no mesmo protocolo, ou ele tentou treinar o OpenAPI?

Comments

[Matheus Altrão]

muito bom