Exponer Datos Legibles como Recursos MCP

Un recurso es la forma en que un servidor MCP entrega datos para que un cliente los lea, direccionado por una URI en lugar de invocado como una función.

Archivos, filas de bases de datos, valores de configuración y respuestas de API son todos encajes naturales para recursos una vez que los piensas como cosas que un cliente puede obtener, no como acciones que un modelo realiza.

Resumen

Los recursos en el SDK de Python MCP se definen con el decorador @mcp.resource(), al que se le pasa una URI o una plantilla de URI como argumento.

Un recurso estático tiene una URI fija, como config://settings, mientras que un recurso con plantilla utiliza marcadores de posición entre llaves, como notes://{name}, que se convierten en parámetros de función.

Dado que un recurso representa una lectura, nunca debe mutar el estado ni desencadenar un efecto secundario; esa distinción es lo que separa un recurso de una herramienta.

Devolver un tipo MIME sensato junto con el contenido ayuda al cliente a decidir cómo renderizar o analizar lo que recibe, ya sea texto plano, JSON o una imagen.

Los recursos se combinan de forma natural con las herramientas: una herramienta puede crear o actualizar algo, y un recurso puede exponer el resultado para su lectura posterior.

Receta

from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("resource-recipes")
 
@mcp.resource("config://settings")
def get_settings() -> str:
    """Devuelve la configuración actual del servidor como JSON."""
    return '{"theme": "dark", "max_results": 20}'
 
@mcp.resource("notes://{name}")
def get_note(name: str) -> str:
    """Devuelve el contenido de una nota con nombre."""
    return f"Contenido de la nota '{name}'"

Cuándo recurrir a esto:

• Los datos están destinados a ser leídos, no a ser actuados, como un archivo, un valor de configuración o una fila de base de datos.
• Desea que el cliente pueda listar y obtener los datos sin que el modelo tenga que construir una llamada a una herramienta.
• El mismo dato podría adjuntarse como contexto directamente por la aplicación, no solo obtenerse a petición del modelo.
• Desea un identificador estable y direccionable (una URI) para una pieza específica de datos que pueda referenciarse de manera consistente.

Ejemplo de Trabajo

# server.py
import json
import sqlite3
from pathlib import Path
 
from mcp.server.fastmcp import FastMCP
 
mcp = FastMCP("docs-resources")
 
DB_PATH = Path(__file__).parent / "articles.db"
DOCS_DIR = Path(__file__).parent / "docs"
 
 
def _get_db() -> sqlite3.Connection:
    conn = sqlite3.connect(DB_PATH)
    conn.row_factory = sqlite3.Row
    return conn
 
 
@mcp.resource("articles://{article_id}")
def get_article(article_id: str) -> str:
    """Devuelve una sola fila de artículo como JSON, direccionada por su id."""
    conn = _get_db()
    try:
        row = conn.execute(
            "SELECT id, title, body FROM articles WHERE id = ?", (article_id,)
        ).fetchone()
        if row is None:
            raise ValueError(f"No se encontró ningún artículo con el id {article_id}")
        return json.dumps(dict(row))
    finally:
        conn.close()
 
 
@mcp.resource("docs://{filename}")
def get_doc_file(filename: str) -> str:
    """Devuelve el texto sin procesar de un archivo markdown del directorio docs."""
    path = (DOCS_DIR / filename).resolve()
    if DOCS_DIR.resolve() not in path.parents:
        raise ValueError("el nombre del archivo debe permanecer dentro del directorio docs")
    if not path.exists():
        raise FileNotFoundError(f"No existe tal archivo: {filename}")
    return path.read_text(encoding="utf-8")
 
 
@mcp.resource("stats://article-count")
def get_article_count() -> str:
    """Devuelve el número total de artículos como un recurso de resumen estático."""
    conn = _get_db()
    try:
        count = conn.execute("SELECT COUNT(*) FROM articles").fetchone()[0]
        return json.dumps({"article_count": count})
    finally:
        conn.close()
 
 
if __name__ == "__main__":
    mcp.run(transport="stdio")

Lo que esto demuestra:

• Un recurso con plantilla (articles://{article_id}) que lee una sola fila de una conexión de base de datos real.
• Un recurso con plantilla (docs://{filename}) que sirve archivos desde el disco, con una protección contra traversales de ruta antes de tocar el sistema de archivos.
• Un recurso estático (stats://article-count) sin parámetros, útil para resúmenes o datos agregados.
• Uso consistente de json.dumps para que los datos estructurados vuelvan en una forma predecible y analizable.
• Lanzamiento de excepciones para una fila faltante o un archivo faltante, exactamente como lo haría una herramienta, ya que los recursos aún pueden fallar.

Análisis Profundo

Cómo Funciona

• @mcp.resource("scheme://path/{param}") registra una plantilla de URI; el SDK extrae los segmentos {param} y los pasa como argumentos de función cuando se lee una URI coincidente.
• Un cliente descubre recursos con list_resources() (para URIs concretas) o list_resource_templates() (para las con plantilla), luego lee una URI específica con read_resource(uri).
• A diferencia de una llamada a herramienta, una lectura de recurso no tiene un objeto de "argumentos" separado; cada parámetro proviene de la URI misma, lo que mantiene los recursos direccionables y cacheados.
• La porción del esquema de la URI (config://, notes://, docs://) es arbitraria y elegida por usted; no es un protocolo de red real, solo un espacio de nombres.
• El SDK infiere un tipo MIME del valor de retorno cuando puede, pero puede ser explícito para cualquier cosa que no sea texto plano.

Elección de un Esquema de URI

Notas de Python

# Protege contra traversales de ruta siempre que un recurso lea desde el disco usando un
# segmento de ruta proporcionado por el usuario.
path = (DOCS_DIR / filename).resolve()
if DOCS_DIR.resolve() not in path.parents:
    raise ValueError("el nombre del archivo debe permanecer dentro del directorio docs")

Parámetros y Valores de Retorno

Trampas

• Tratar un recurso como una acción. Un recurso llamado send_email://{to} implica un efecto secundario y engaña a los clientes que asumen que los recursos son seguros de leer repetidamente. Solución: mover cualquier cosa con un efecto secundario a una herramienta.
• Sin protección contra traversales de ruta en recursos basados en el sistema de archivos. Una URI como docs://../../etc/passwd puede escapar del directorio previsto si construyes una ruta de forma ingenua. Solución: resuelve la ruta y confirma que permanece dentro de la raíz permitida antes de leer.
• Devolver texto no estructurado para lo que en realidad son datos estructurados. Los llamadores tienen que analizar formatos ad hoc en lugar de JSON. Solución: devuelve json.dumps(...) para cualquier cosa con más de un campo.
• Abrir una conexión de base de datos por recurso sin cerrarla. Bajo carga, esto filtra conexiones y eventualmente agota el pool. Solución: usa un try/finally (como se muestra arriba) o un gestor de contexto de conexión.
• Sobrecargar una plantilla de recurso para que también acepte parámetros opcionales de estilo de consulta. Las plantillas de URI en MCP se basan en la ruta, no en la cadena de consulta, por lo que esto se vuelve incómodo e inconsistente. Solución: usa recursos separados o una herramienta si la lógica de selección de datos se vuelve lo suficientemente compleja como para necesitar filtros opcionales.
• Devolver silenciosamente una cadena vacía cuando una búsqueda falla. Un llamador no puede distinguir entre "sin datos" y "ocurrió un error". Solución: lanza una excepción con un mensaje claro cuando el recurso solicitado realmente no existe.

Alternativas

Preguntas Frecuentes

Relacionado

• Comprendiendo MCP: Herramientas, Recursos y Prompts - la distinción conceptual entre recursos, herramientas y prompts.
• Conceptos Básicos de los Conceptos Centrales de MCP - un servidor y cliente stdio mínimo sobre el cual construir recursos.
• Definición de Herramientas Invocables en un Servidor MCP - la primitiva hermana para acciones y cálculos.
• Comparación de Herramientas, Recursos y Prompts de MCP - decidir qué primitiva se ajusta a una capacidad dada.
• Mejores Prácticas de Conceptos Centrales de MCP - una lista de verificación para el diseño de URI de recursos.

Versiones de Stack: Escrito contra la línea de modelos Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado), y Claude Haiku 4.5 - y la especificación actual del Protocolo de Contexto del Modelo. Los nombres de los modelos, las versiones del SDK y la especificación MCP cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs y modelcontextprotocol.io antes de confiar en ellos.