Cargando
Cargando

Los recursos en los servidores MCP te permiten exponer datos a los clientes, de forma 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.

Comprendiendo los recursos a través de un ejemplo

Supongamos que quieres crear una función de mención de documentos en la que los usuarios puedan escribir @nombre_documento para hacer referencia a 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)

Un "@" escrito en una indicación de chat abre una lista de documentos, como deposition.md y spec.md, cada uno etiquetado como "Resource".

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

Escribir un signo de arroba muestra una lista de documentos como design.md, cada uno etiquetado como "Resource", y una mención inyecta el contenido de report.pdf.

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 funciona como una dirección para el recurso al que deseas acceder.

Diagrama de un servidor MCP que contiene dos definiciones de recursos, list_docs y fetch_doc, mostradas en el código a continuación.

Tipos de recursos

Hay dos tipos de recursos:

Código decorador para un recurso directo sin parámetros en su URI y un recurso con plantilla con doc_id, descrito a continuación.

  • 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 de texto, 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:

Pestaña de recursos del MCP Inspector, con docs://documents listado bajo Resources y nada listado bajo Resource Templates.

  • Resources: Muestra 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.

Pestaña de recursos del MCP Inspector: leer docs://documents devuelve una lista JSON de nombres de archivo como deposition.md y plan.md.

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 comprender el formato de respuesta
  • El SDK maneja la serialización automáticamente
  • Los nombres de los 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, permitiendo funciones como menciones de documentos, exploración de archivos o cualquier escenario en el que necesites obtener información desde tu servidor.