Claude Academy
Cargando

Definiendo recursos

Lección 68 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 en los que 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 autocompletar)
  • Obtener el contenido de un documento específico (cuando se menciona)

Diapositiva de funcionalidad: los usuarios pueden mencionar un documento escribiendo @nombre_doc; al escribir @ se muestra una lista de todos los documentos disponibles en un autocompletado, y el contenido de un documento mencionado se inyecta automáticamente en el prompt

Cuando un usuario menciona un documento, tu sistema inyecta automáticamente el contenido del documento en el prompt enviado a Claude, eliminando la necesidad de que Claude use herramientas para obtener la información.

Diagrama de un usuario preguntando "¿Qué contiene el archivo @report.pdf?" — nuestro código envuelve la consulta en un prompt para Claude con el contenido del documento referenciado inyectado dentro de una etiqueta de documento

Cómo funcionan los recursos

Los recursos siguen un patrón de solicitud-respuesta. Cuando tu cliente necesita datos, envía una ReadResourceRequest con un URI para identificar qué recurso desea. El servidor MCP procesa esta solicitud y devuelve los datos en un ReadResourceResult.

Diagrama de secuencia: el usuario escribe "¿Qué contiene el @…", nuestro código le pide al cliente MCP una lista de nombres de documentos para el autocompletado, y el cliente envía una ReadResourceRequest con el URI docs://documents al servidor MCP

El flujo se ve así: tu código solicita un recurso al cliente MCP, que reenvía la solicitud al servidor MCP. El servidor procesa el URI, ejecuta la función correspondiente y devuelve el resultado.

Diagrama de secuencia continuado: el servidor MCP devuelve un ReadResourceResult que contiene la lista de nombres de documentos, que el cliente MCP pasa de vuelta a nuestro código para incluirlo en el autocompletado

Tipos de recursos

Hay dos tipos de recursos:

Recursos directos

Los recursos directos tienen URIs estáticos que nunca cambian. Son perfectos para operaciones que no necesitan parámetros.

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

Recursos con plantilla

Los recursos con plantilla incluyen parámetros en sus URIs. El SDK de Python analiza automáticamente estos parámetros y los pasa como argumentos de palabra clave a tu función.

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]

Comparación lado a lado: un Recurso Directo cuyo URI no contiene ningún parámetro, y un Recurso con Plantilla cuyo URI contiene uno o más parámetros que el SDK de Python analiza y pasa como argumentos a tu función

Detalles de implementación

Los recursos pueden devolver cualquier tipo de dato: cadenas de texto, JSON, datos binarios, etc. Usa el parámetro mime_type para darle a los clientes una pista sobre qué tipo de datos estás devolviendo:

  • "application/json" para datos estructurados
  • "text/plain" para texto sin formato
  • "application/pdf" para archivos binarios

El SDK de Python de MCP serializa automáticamente tus valores de retorno. No necesitas convertir manualmente los objetos a cadenas JSON; simplemente devuelve la estructura de datos y deja que el SDK se encargue de la serialización.

Probando tus recursos

Puedes probar los recursos usando el MCP Inspector. Inicia tu servidor con:

uv run mcp dev mcp_server.py

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

  • Resources - Lista tus recursos directos/estáticos
  • Resource Templates - Lista tus recursos con plantilla

MCP Inspector con la pestaña Resources abierta, mostrando el recurso directo docs://documents bajo Resources, la plantilla fetch_doc bajo Resource Templates, y la respuesta JSON para docs://documents con su URI, mimeType y la lista serializada de nombres de documentos

Haz clic en cualquier recurso para probarlo. Para los recursos con plantilla, deberás proporcionar valores para los parámetros. El inspector te muestra la estructura exacta de la respuesta que recibirá tu cliente, incluyendo el tipo MIME y los datos serializados.

Los recursos proporcionan una forma limpia de exponer datos de solo lectura desde tu servidor MCP, facilitando que los clientes obtengan información sin la complejidad de las llamadas a herramientas.