Aprendizados de construir um servidor MCP de catálogo de cursos — da POC à produção.

O que é o Model Context Protocol (MCP)?

O Model Context Protocol (MCP) é um padrão aberto que permite que aplicações de IA (como o Cursor, Claude Desktop ou outros hosts) se conectem a fontes de dados e ferramentas externas de forma padronizada.

Pense no MCP como uma tomada universal: em vez de cada editor inventar sua própria integração com bancos, APIs e scripts, todos falam o mesmo protocolo — JSON-RPC 2.0 — sobre um transporte (stdio ou HTTP).

┌─────────────┐     JSON-RPC      ┌─────────────┐     HTTP/SQL    ┌─────────────┐
│   Cursor    │ ◄──────────────► │ MCP Server  │ ◄─────────────► │  Backend    │
│  (cliente)  │   tools/call     │  (adaptador)│                 │  (dados)    │
│             │   resources/read │             │                 │             │
└─────────────┘                   └─────────────┘                 └─────────────┘

O MCP não substitui sua API de negócio. Ele é a camada de adaptação entre o modelo de linguagem e o mundo real.

As três primitivas do MCP

O protocolo expõe três tipos de capacidade. Entender a diferença entre elas é o ponto central deste artigo.

Tools — ações invocáveis

Tools são funções que o modelo pode chamar. Cada tool tem nome, descrição, schema de entrada (JSON Schema via Zod) e retorna um resultado.

{
  "name": "criar_curso",
  "description": "Cria um novo curso no catálogo.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "titulo": { "type": "string" },
      "cargaHoraria": { "type": "number" }
    },
    "required": ["titulo", "cargaHoraria"]
  }
}

Quando o modelo usa: o usuário pede uma ação — "crie um curso de NestJS com 12 horas" — e o modelo decide invocar criar_curso.

Características:

• Pode ter efeito colateral (criar, atualizar, deletar, enviar email)
• Retorna erro estruturado com isError: true para o modelo se corrigir
• O humano deve estar no loop (aprovação, logs, confirmação)

Resources — dados passivos legíveis

Resources são dados identificados por URI que o host ou o modelo podem ler para obter contexto.

cursos://catalogo          → catálogo completo (JSON)
cursos://f47ac10b-58cc-... → detalhes de um curso
file:///docs/guia.md       → documento estático

Quando o modelo usa: o usuário quer consultar informação — "quais cursos existem?" — ou o host anexa o resource automaticamente ao contexto.

Características:

• Somente leitura (por design)
• Identificados por URI (esquemas customizados são permitidos)
• Podem ser fixos (cursos://catalogo) ou templates (cursos://{uuid})
• Application-driven: o host decide como exibir e quando incluir no contexto

Prompts — templates reutilizáveis

Prompts são modelos de instrução parametrizados que guiam o modelo por um fluxo conhecido.

/plan-vacation destination=Barcelona duration=7 budget=3000

Quando usar: fluxos repetíveis onde você quer consistência — onboarding, checklists, workflows de revisão.

A regra de ouro: Tool vs Resource

Exemplo concreto: catálogo de cursos

Na V2 do nosso projeto, tínhamos três tools:

listar_cursos   → leitura (mas exposta como Tool)
buscar_curso    → leitura (mas exposta como Tool)
criar_curso     → escrita ✓

Na V3, separamos corretamente:

Resources:
  cursos://catalogo     → leitura do catálogo
  cursos://{uuid}       → leitura de um curso

Tools:
  criar_curso           → escrita
  atualizar_curso       → escrita
  arquivar_curso        → escrita

Por que mudamos? Porque listar_cursos e buscar_curso não tinham efeito colateral — eram consultas disfarçadas de ações. Isso gerava redundância: o modelo podia escolher entre duas formas de fazer a mesma coisa, sem critério claro.

Quando usar Tools

✅ Use Tool quando...

❌ Não use Tool quando...

Quando usar Resources

✅ Use Resource quando...

❌ Não use Resource quando...

Resource fixo vs template

Quando usar Prompts

✅ Use Prompt quando...

• Existe um fluxo repetível com parâmetros conhecidos
• Você quer consistência na forma como o modelo aborda uma tarefa
• O usuário invoca explicitamente (slash command, palette)

❌ Não use Prompt quando...

• A tarefa é ad hoc e imprevisível → deixe o modelo usar tools/resources livremente
• O fluxo depende de muitas variáveis dinâmicas → tools são mais flexíveis

Transporte: stdio vs HTTP

O MCP define como cliente e server se comunicam. Isso é independente de Tools/Resources.

stdio — nosso caminho na POC

{
  "mcpServers": {
    "mcp-cursos": {
      "command": "node",
      "args": ["apps/mcp/dist/mcp.js"],
      "env": {
        "BACKEND_URL": "http://localhost:3000/mcp/v1",
        "API_KEY": "sua-chave"
      }
    }
  }
}

Streamable HTTP — evolução futura

Server expõe URL (https://api.exemplo.com/mcp); auth via header Authorization: Bearer. Indicado para produção compartilhada entre times.

Arquitetura: MCP não é o backend

Um erro comum é colocar toda a lógica dentro do MCP server. A arquitetura que adotamos separa responsabilidades:

┌──────────────────────────────────────────────────────────┐
│  apps/mcp          Adaptador MCP (stdio)                 │
│  - Registra tools e resources                            │
│  - Traduz MCP → HTTP                                     │
│  - Não conhece banco de dados                            │
└────────────────────────┬─────────────────────────────────┘
                         │ HTTP + API Key
                         ▼
┌──────────────────────────────────────────────────────────┐
│  apps/backend      API de negócio (NestJS)               │
│  - REST /mcp/v1/cursos                                   │
│  - Auth, validação, regras de domínio                    │
│  - TypeORM + SQLite                                      │
└──────────────────────────────────────────────────────────┘

Por quê?

• Backend testável isoladamente (curl, Postman)
• MCP fino — só adaptação de protocolo
• Mesma API serve MCP, integrações externas e mobile
• Deploy independente (MCP local, backend remoto)

A spec MCP não prescreve como o server fala com sua API. REST, gRPC ou chamada in-process — escolha de implementação.

Evolução do nosso projeto: V1 → V2 → V3

A V3 aplicou a regra: Resource = ler, Tool = agir.

Decisões de domínio que impactam o MCP

Arquivamento (soft delete)

Em vez de deletar cursos, arquivamos — arquivado: true. O curso some do catálogo ativo, mas continua consultável por URI.

Atualização parcial

atualizar_curso aceita titulo e/ou cargaHoraria — pelo menos um obrigatório. Alinha com PATCH REST e evita reenviar dados desnecessários.

Notificações: subscribe e listChanged

A spec MCP permite que o server notifique o cliente quando resources mudam (resources/subscribe, resources/listChanged).

Com subscribe: após criar_curso, o Cursor poderia atualizar cursos://catalogo automaticamente no contexto.

Sem subscribe (nossa V3): o modelo relê o resource quando o usuário pede — "mostra o catálogo atualizado".

Para a maioria dos casos, relê quando necessário é suficiente. Subscribe faz sentido quando o catálogo muda constantemente e o host precisa de refresh automático.

Checklist rápido para seu próximo MCP

Antes de implementar, pergunte:

1. O que é leitura? → Resource com URI clara
2. O que é ação? → Tool com schema validado
3. O MCP fala direto com o banco? → Prefira não; use API intermediária
4. stdio ou HTTP? → stdio para local; HTTP para remoto
5. Preciso de notificações? → Comece sem; adicione se o refresh manual incomodar
6. Tools de leitura coexistem com Resources? → Evite redundância

Referências

• Model Context Protocol — Documentação oficial
• Understanding MCP servers — Tools, Resources, Prompts
• Specification: Tools
• Specification: Resources
• Repositório de referência: projeto mcp-cursos — POC com V1 (mock), V2 (backend), V3 (resources)

Conclusão

MCP não é magia — é protocolo. Tools são verbos, Resources são substantivos, Prompts são roteiros. Separar leitura de escrita torna seu server previsível para o modelo e mais fácil de manter para você.

Comece simples: stdio, poucas tools, mock ou API mínima. Evolua para Resources quando a leitura passiva fizer sentido, e para HTTP remoto quando precisar compartilhar o backend entre clientes.

O catálogo de cursos que construímos passou por três versões até chegar nesse modelo. Cada iteração ensinou algo — e documentar essas decisões (ADRs, glossário, este post) evita que o próximo dev reinvente a roda.

Escrito com base na implementação do projeto mcp-cursos — grill sessions, ADRs e código real.