Módulo 3: Tres Primitivas — Resources, Tools, Prompts

Descripción de la cápsula

Has recorrido un camino importante. En el Módulo 1 entendiste por qué MCP existe — el problema M×N y cómo un protocolo estándar lo resuelve. En el Módulo 2 aprendiste cómo funciona — la arquitectura Host-Client-Server y el flujo de datos entre capas. Ahora llega la pregunta natural: ¿qué puede hacer un MCP server?

La respuesta cabe en tres palabras: Resources, Tools, Prompts.

Estas son las tres primitivas — los building blocks fundamentales — que todo MCP server expone. No hay una cuarta. Cualquier capability que un MCP server ofrece se implementa como una de estas tres. Entenderlas es la diferencia entre "sé qué es MCP" y "puedo diseñar un MCP server."

Este módulo es el puente entre teoría y construcción. Al terminarlo, no solo entenderás las primitivas conceptualmente — tendrás un MCP server mínimo funcionando con 1 resource, 1 tool, y 1 prompt.

¿Dónde estamos?

Contexto en la guía

Phase 1: Fundamentos MCP (Módulos 1-3)
  ✅ Módulo 1: Qué es MCP y por qué importa
  ✅ Módulo 2: Arquitectura Host-Client-Server
  → Módulo 3: Tres Primitivas (ESTÁS AQUÍ)

Phase 2: Construir MCP Servers (Módulos 4-6)
  ○ Módulo 4: MCP Server en TypeScript
  ○ Módulo 5: MCP Server en Python
  ○ Módulo 6: MCP Apps y UI Interactivo

Phase 3: Producción (Módulos 7-8)
  ○ Módulo 7: Testing, Debugging e Integración
  ○ Módulo 8: Proyecto — MCP Server Real

Lo que ya sabes

De los módulos anteriores traes:

El modelo mental M×N vs M+N — por qué un protocolo estándar es necesario
La arquitectura Host-Client-Server — cómo se conectan las piezas
El flujo de un request — cómo viajan los datos del usuario al server y de vuelta
Experiencia práctica — configuraste y usaste el Filesystem MCP Server en Claude Code

Lo que falta

Sabes que un MCP server expone "capabilities" al host. Pero ¿qué tipos de capabilities existen? ¿Cómo decides si algo debe ser un resource, un tool, o un prompt? ¿Cómo se implementa cada uno? Eso es exactamente lo que cubre este módulo.

Objetivo del módulo

Al completar este módulo, serás capaz de:

✅ Explicar la diferencia entre Resources, Tools y Prompts con ejemplos concretos
✅ Decidir cuándo usar cada primitiva: "necesito exponer datos → Resource; necesito ejecutar una acción → Tool; necesito estandarizar un flujo → Prompt"
✅ Implementar un Resource que expone datos estáticos y dinámicos
✅ Implementar un Tool que ejecuta una función con side effects
✅ Implementar un Prompt que genera templates parametrizados
✅ Construir un MCP server mínimo con las 3 primitivas funcionando juntas
✅ Conectar tu server a Claude Code y verificar que funciona

Las 3 primitivas: visión general

Antes de profundizar en cada una (cápsulas 02-04), necesitas el mapa completo.

Analogía: una tienda de herramientas

Imagina que un MCP server es una tienda de herramientas:

MCP Server = Tienda de herramientas
│
├── Resources (el catálogo)
│   "Puedo mostrarte qué tenemos en stock"
│   → Datos que puedes leer
│   → No modifica nada — solo consulta
│
├── Tools (los servicios)
│   "Puedo cortar, soldar, pintar por ti"
│   → Funciones que ejecutan acciones
│   → Pueden modificar estado
│
└── Prompts (las recetas de proyectos)
    "Aquí tienes instrucciones paso a paso"
    → Templates reutilizables
    → Estandarizan cómo pedir cosas

Tabla comparativa rápida

Aspecto	Resources	Tools	Prompts
Qué es	Datos contextuales	Funciones ejecutables	Templates reutilizables
Dirección	Pull: cliente pide, server responde	Invocación: modelo llama, server ejecuta	Template: cliente pide, server genera
Side effects	No — solo lectura	Sí — puede modificar estado	No — solo genera texto
Analogía	Leer un libro	Usar una herramienta	Seguir una receta
Ejemplo	Leer archivo, consultar DB	Crear archivo, enviar email	Template de code review
Quién inicia	El cliente/usuario pide datos	El modelo decide invocar	El usuario selecciona template
Control	Controlado por la aplicación	Controlado por el modelo (con aprobación)	Controlado por el usuario

El flujo natural

En un server real, las tres primitivas se complementan:

1. Resource → "¿Qué archivos hay en el proyecto?"
   Server responde con la lista de archivos

2. Tool → "Refactoriza este archivo"
   Server ejecuta la refactorización

3. Prompt → "Usa el template de code review"
   Server genera el prompt con parámetros del usuario

El resource expone los datos, el tool actúa sobre ellos, y el prompt estandariza cómo se piden las cosas. Cada uno tiene su rol.

Árbol de decisión: ¿qué primitiva necesito?

Cuando diseñes tu MCP server, este árbol te ayuda a decidir:

¿El modelo necesita LEER datos?
├── Sí → ¿Los parámetros caben en un URI?
│   ├── Sí → Resource (con URI template si es dinámico)
│   └── No → Tool de solo lectura (con schema para parámetros complejos)
└── No
    ↓
¿El modelo necesita EJECUTAR una acción con side effects?
├── Sí → Tool
│   └── ¿Es una acción destructiva?
│       ├── Sí → Tool con patrón dryRun
│       └── No → Tool estándar
└── No
    ↓
¿Quieres ESTANDARIZAR cómo el usuario pide algo?
├── Sí → Prompt
│   └── ¿Necesita contexto de archivos/datos?
│       ├── Sí → Prompt con resource embebido
│       └── No → Prompt con solo texto
└── No → Probablemente no necesitas MCP para esto

Ejemplos de MCP servers reales y sus primitivas

Para anclar esto en la realidad, veamos cómo servers existentes usan las primitivas:

Filesystem Server (Anthropic oficial):

Resources: (no expone resources, usa tools para todo)
Tools:
├── read_file         → Lee un archivo
├── write_file        → Escribe un archivo
├── list_directory    → Lista un directorio
├── search_files      → Busca archivos
├── create_directory  → Crea un directorio
├── move_file         → Mueve/renombra
└── ...
Prompts: (no define prompts)

Este server es 100% tools porque todas las operaciones son acciones con inputs variables. Nota que read_file es un tool y no un resource — porque la ruta del archivo viene como parámetro complejo, no como URI predefinido.

Un hipotético GitHub Server:

Resources:
├── github://repos/{owner}/{repo}/readme      → README del repo
├── github://repos/{owner}/{repo}/issues/open  → Issues abiertos
└── github://repos/{owner}/{repo}/stats        → Estadísticas
Tools:
├── create_issue     → Crea un issue
├── close_issue      → Cierra un issue
├── create_pr        → Crea un pull request
├── merge_pr         → Merge un PR
└── add_comment      → Agrega un comentario
Prompts:
├── bug-report       → Template estandarizado de bug report
├── pr-description   → Genera descripción de PR
└── code-review      → Template de code review con criterios

Este server usa las 3 primitivas: resources para datos de consulta, tools para acciones, prompts para estandarizar interacciones comunes.

El modelo mental: piensa en capas

Una forma útil de pensar en las primitivas es como capas de un restaurante:

┌─────────────────────────────────────┐
│           MENÚ (Prompts)            │
│  Lo que el cliente ve y elige       │
│  "Combo #3: hamburguesa + papas"    │
├─────────────────────────────────────┤
│          COCINA (Tools)             │
│  Donde se ejecutan las acciones     │
│  "Cocinar hamburguesa, freír papas" │
├─────────────────────────────────────┤
│        INVENTARIO (Resources)       │
│  Los ingredientes disponibles       │
│  "Pan, carne, papas, aceite"        │
└─────────────────────────────────────┘

El menú (Prompts) estandariza cómo el cliente pide — no necesita saber los detalles internos.
La cocina (Tools) ejecuta las acciones reales — transforma ingredientes en platos.
El inventario (Resources) provee los datos base — qué hay disponible, cantidades, estado.

El cliente no va al inventario directamente. No entra a la cocina. Usa el menú. Pero detrás, todo funciona como un sistema integrado.

Roadmap del módulo

Cápsula	Tema	Qué aprenderás
02	Resources: datos contextuales	Exponer datos que el modelo puede leer — archivos, DB records, API responses
03	Tools: funciones ejecutables	Crear funciones que el modelo puede invocar — con side effects reales
04	Prompts: templates reutilizables	Diseñar templates parametrizados para interacciones comunes
05	Combinando primitivas	Cómo las 3 trabajan juntas en un server real
06	Mini-proyecto	Implementar un MCP server con 1 resource, 1 tool, 1 prompt

Flujo de aprendizaje

La progresión es deliberada:

Resource (cápsula 02) — empezamos con la primitiva más simple: datos de solo lectura. Sin side effects, sin complejidad.
Tool (cápsula 03) — subimos la complejidad: funciones que ejecutan acciones y pueden modificar estado. Requiere schemas, validación, permisos.
Prompt (cápsula 04) — la menos intuitiva para developers: templates reutilizables. No es código que ejecuta — es texto que guía.
Combinación (cápsula 05) — las 3 juntas: cómo un server real orquesta resources, tools y prompts como un sistema cohesivo.
Mini-proyecto (cápsula 06) — construyes tu primer MCP server funcional con las 3 primitivas.

Cada cápsula tiene ejemplos en TypeScript (primario) y Python (secundario). Ambos SDKs oficiales están soportados.

Conexión con el proyecto

Mini-proyecto de este módulo

Vas a construir un MCP server mínimo con:

1 Resource: listar archivos de un directorio
1 Tool: crear un archivo nuevo
1 Prompt: template de refactoring

Es deliberadamente simple. El objetivo es que entiendas las 3 primitivas en acción, no que construyas algo complejo. La complejidad viene en los módulos 4-6.

Conexión con el proyecto integrador (Módulo 8)

El server mínimo de este módulo es la semilla del proyecto final. En el Módulo 4 lo escalarás con TypeScript completo (múltiples tools, Zod schemas, transports). En el Módulo 8 lo convertirás en un server production-ready conectado a una API/database real. Los patrones que aprendes aquí — cómo definir resources, tools y prompts — son exactamente los que usarás a escala.

Prerequisitos

Para este módulo necesitas:

✅ Claude Code instalado y funcionando
✅ Node.js v18+ y npm instalados
✅ Haber completado módulos 1 y 2 (conceptos y arquitectura)
✅ Haber usado el Filesystem MCP Server (módulo 1, cápsula 05)

Recomendado pero no obligatorio:

Familiaridad básica con TypeScript (puedes aprender sobre la marcha)
Familiaridad básica con Python (solo necesario si eliges la implementación Python)
Haber explorado el Filesystem Server más allá de los ejemplos del módulo 1

Límites: qué NO se cubre en este módulo

❌ Implementación completa en TypeScript — Eso viene en módulo 4
❌ Implementación completa en Python — Eso viene en módulo 5
❌ Zod schemas avanzados — Se cubren en módulo 4
❌ Transports (stdio, HTTP/SSE) — Se cubren en módulo 4
❌ Testing y debugging — Se cubren en módulo 7
❌ MCP Apps y UI — Se cubren en módulo 6

Este módulo es conceptual + primer contacto práctico. Estás construyendo el "qué puede hacer" antes del "cómo hacerlo a escala."

Evidencia de éxito

Al terminar este módulo, sabrás que tuviste éxito si:

✅ Puedes explicar Resources, Tools y Prompts a un colega usando ejemplos concretos
✅ Ante un caso de uso, puedes decidir qué primitiva(s) necesitas
✅ Tienes un MCP server mínimo corriendo con 1 de cada primitiva
✅ Has conectado tu server a Claude Code y lo has probado
✅ Entiendes cómo las 3 primitivas se combinan en un server real
✅ Te sientes preparado para escalar esto en TypeScript (módulo 4)

Decisión de diseño: ¿por qué solo 3 primitivas?

Puede parecer limitante — ¿solo tres tipos de capability? Pero esa simplicidad es intencional. Piensa en HTML: toda la web se construye con ~100 tags, pero la mayoría de páginas usan solo 20-30. La simplicidad del conjunto no limita lo que puedes construir — lo habilita.

Resources cubren cualquier dato que el modelo necesite leer

No importa de dónde vengan los datos:

Archivos del filesystem → file:///src/main.ts
Records de una base de datos → db://users/123
Responses de APIs externas → api://weather/madrid
Configuraciones del sistema → config://app/settings
Logs y métricas → metrics://server/cpu
Estado de servicios → status://docker/containers

Todo dato que puedas poner en un URI, puedes exponerlo como Resource.

Tools cubren cualquier acción que el modelo necesite ejecutar

Si tiene un verbo, probablemente es un Tool:

Crear: archivos, registros, issues, PRs
Leer con parámetros complejos: búsquedas, queries con filtros
Actualizar: modificar datos, configuraciones, estado
Eliminar: borrar registros, archivos, recursos
Ejecutar: deploy, test, lint, build
Enviar: emails, notificaciones, mensajes

Todo lo que modifica estado o requiere parámetros validados, es un Tool.

Prompts cubren cualquier interacción que quieras estandarizar

Si repites un patrón de interacción, encapsúlalo en un Prompt:

Templates de code review con criterios específicos
Wizards de generación de código paso a paso
Flujos de debugging con formato estructurado
Reportes estandarizados (standup, sprint review)
Documentación con formato consistente

No necesitas una cuarta primitiva porque estas tres cubren el espectro completo: leer datos (Resource), ejecutar acciones (Tool), y estandarizar interacciones (Prompt).

Preguntas frecuentes antes de empezar

"¿Necesito las 3 primitivas en mi server?"

No. Muchos servers solo usan Tools (como el Filesystem Server). Otros solo exponen Resources (un server de métricas). Algunos solo tienen Prompts (un server de templates). Usa las que necesites.

"¿Las primitivas se llaman entre sí?"

No directamente a nivel de protocolo. Pero en tu código, un Tool puede leer datos internamente (como lo haría un Resource), y un Prompt puede generar instrucciones que lleven al modelo a usar un Tool. La integración ocurre a nivel de diseño, no de protocolo.

"¿Cuál es la más importante?"

Tools. Es la primitiva más usada en la práctica. Si tu server solo pudiera tener un tipo de primitiva, serían Tools. Pero las 3 juntas hacen un server mucho más poderoso y usable.

"¿Puedo crear mis propios tipos de primitivas?"

No en el protocolo estándar. MCP define exactamente 3 primitivas. Si algo no cabe en Resources, Tools o Prompts, probablemente necesitas repensar tu diseño — casi todo cabe si lo modelas correctamente.

Preparación mental

Antes de entrar a las cápsulas técnicas, ten en cuenta esto:

No necesitas memorizar las APIs. Lo importante es el modelo mental — saber cuándo usar cada primitiva. La sintaxis la consultas en la documentación.
TypeScript primero, Python segundo. Si no conoces TypeScript, no te preocupes — los ejemplos son autoexplicativos y los patrones son universales.
El mini-proyecto es el objetivo. Todo lo que aprendes en las cápsulas 02-05 converge en la cápsula 06, donde construyes un server funcional.

Resumen

Este módulo cubre el qué puede hacer un MCP server — las 3 primitivas
Resources = datos de solo lectura que el modelo consulta
Tools = funciones ejecutables con side effects
Prompts = templates reutilizables con parámetros
Progresión: Resource → Tool → Prompt → Combinación → Mini-proyecto
Al terminar tendrás un MCP server mínimo con las 3 primitivas funcionando
Este server mínimo es la semilla que escalarás en módulos 4-8

Recursos adicionales

MCP Specification — Primitives - Especificación oficial de Resources, Tools y Prompts
MCP TypeScript SDK - SDK que usarás para implementar las primitivas
MCP Python SDK - Alternativa en Python
Building MCP Servers (Anthropic Docs) - Guía oficial de construcción
MCP Inspector - Herramienta para inspeccionar resources, tools y prompts
Awesome MCP Servers - Ejemplos reales de servers con diferentes combinaciones de primitivas

Nota sobre los ejemplos de código

A lo largo de este módulo encontrarás ejemplos en TypeScript (lenguaje primario) y Python (lenguaje secundario). Ambos SDKs oficiales de MCP están soportados y la elección depende de tu preferencia:

TypeScript SDK (@modelcontextprotocol/sdk) — Más maduro, más servidores de referencia disponibles, usa Zod para validación de schemas
Python SDK (pip install mcp) — Más conciso gracias a decoradores, ideal si tu stack es Python-centric, usa type hints y Pydantic

En el módulo 4 profundizarás en TypeScript y en el módulo 5 en Python. Aquí verás ambos para que puedas comparar y elegir.

Siguiente cápsula: Resources — datos contextuales que el modelo puede leer. La primitiva más simple y el punto de entrada perfecto para entender cómo un MCP server expone capabilities.

← AnteriorFlujo Completo Request-Response + Mini-Proyecto Siguiente →Resources: Datos Contextuales que el Modelo Puede Leer