Claude Academy
Cargando

Definiendo recursos

Lección 5310 min

Los recursos en los servidores MCP te permiten exponer datos a los clientes, de manera similar a los manejadores de solicitudes GET en un servidor HTTP típico. Son perfectos para escenarios donde necesitas obtener información en lugar de realizar acciones.

Entendiendo los recursos a través de un ejemplo

Supongamos que quieres crear una función de mención de documentos donde los usuarios puedan escribir @nombre_documento para referenciar archivos. Esto requiere dos operaciones:

  • Obtener una lista de todos los documentos disponibles (para autocompletado)
  • Obtener el contenido de un documento específico (cuando se menciona)

Cuando un usuario escribe @, necesitas mostrar los documentos disponibles. Cuando envían un mensaje con una mención, automáticamente inyectas el contenido de ese documento en el prompt enviado a Claude.

Cómo funcionan los recursos

Los recursos siguen un patrón de solicitud-respuesta. Tu cliente envía una ReadResourceRequest con un URI, y el servidor MCP responde con los datos. El URI actúa como una dirección para el recurso al que deseas acceder.

Tipos de recursos

Hay dos tipos de recursos:

  • Recursos directos: URIs estáticos que no cambian, como docs://documents
  • Recursos con plantilla: URIs con parámetros, como docs://documents/{doc_id}

Para los recursos con plantilla, el SDK de Python analiza automáticamente los parámetros del URI y los pasa como argumentos de palabra clave a tu función.

Implementando recursos

Los recursos se definen usando el decorador @mcp.resource(). Así es como se crean ambos tipos:

Recurso directo (Listar documentos)

python
@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    return list(docs.keys())

Recurso con plantilla (Obtener documento)

python
@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    return docs[doc_id]

Tipos MIME

Los recursos pueden devolver cualquier tipo de datos: cadenas, JSON, binarios, etc. El parámetro mime_type le da a los clientes una pista sobre qué tipo de datos estás devolviendo:

  • application/json - Datos JSON estructurados
  • text/plain - Contenido de texto plano
  • Cualquier otro tipo MIME válido para diferentes formatos de datos

El SDK de Python de MCP serializa automáticamente tus valores de retorno. No necesitas convertirlos manualmente a cadenas JSON.

Probando recursos

Puedes probar tus recursos usando el MCP Inspector. Ejecuta tu servidor con:

bash
uv run mcp dev mcp_server.py

Luego conéctate al inspector en tu navegador. Verás:

  • Resources: Lista tus recursos directos/estáticos
  • Resource Templates: Muestra los recursos con plantilla que aceptan parámetros

Haz clic en cualquier recurso para probarlo y ver la estructura exacta de respuesta que recibirá tu cliente.

Puntos clave

  • Los recursos exponen datos, las herramientas realizan acciones
  • Usa recursos directos para datos estáticos, recursos con plantilla para consultas parametrizadas
  • Los tipos MIME ayudan a los clientes a entender el formato de respuesta
  • El SDK maneja la serialización automáticamente
  • Los nombres de parámetros en los URIs con plantilla se convierten en argumentos de función

Los recursos proporcionan una forma limpia de poner datos a disposición de los clientes MCP, habilitando funciones como menciones de documentos, navegación de archivos, o cualquier escenario donde necesites obtener información de tu servidor.