MCP 실전: 도구·리소스와 사용 시점

출처: Dev.to

MCP 서버 구축 학습 — 카탈로그에서 POC부터 프로덕션까지

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 │             │                 │             │
└─────────────┘                   └─────────────┘                 └─────────────┘

Enter fullscreen mode
Exit fullscreen mode

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.

MCP의 세 가지 원시 유형

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

도구 — 호출 가능한 행동
Tools são 함수 호출 가능입니다. Cada tool possui 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"]
   }
}

Enter fullscreen mode
Exit fullscreen mode

Quando 모델을 사용하는가: 사용자가 액션을 요청 — “NestJS 코스 12시간 만들기” — 이고 모델은 criar_curso를 호출합니다.

특징:

• Puede 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)

Resource — 읽기 전용 수동 데이터
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  

Enter fullscreen mode
Exit fullscreen mode

Quando 모델을 사용하는가: 사용자가 정보를 조회하고자 할 때 — “어떤 코스가 존재하는가?” — 혹은 호스트가 자동으로 자원을 컨텍스트에 첨부합니다.

특징:

• 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

Prompt — 재사용 가능한 템플릿

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

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

Enter fullscreen mode
Exit fullscreen mode

Quando 사용: 반복되는 흐름으로 일관성을 원할 때 — 온보딩, 체크리스트, 검토 워크플로.

❌ Não use Prompt quando…

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

Transportes: 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"
       }
     }
   }
}

Enter fullscreen mode
Exit fullscreen mode

Vantagens: simples, zero config de rede, padrão do ecossistema.

Limitação: processo local —