La arquitectura de mi sitio personal para personas, software y agentes

Reconstruí mi sitio personal con tres capas: una web para las personas, una API para el software y MCP para los agentes.

Parece más complicado que un sitio personal normal, pero la idea es sencilla. El mismo trabajo debería poder consultarse mediante interfaces distintas según quién, o qué, intente entenderlo. Una persona quiere páginas, un script quiere JSON y un agente de IA quiere herramientas. La arquitectura sirve a los tres sin duplicar el contenido.

La capa para las personas

La web sigue siendo la interfaz principal.

Tiene las páginas que la gente espera:

• inicio;
• acerca de mí;
• productos;
• proyectos;
• notas;
• contacto.

Esta capa se centra en la confianza, la claridad, el ritmo de lectura y la jerarquía visual. Debe responder con rapidez a preguntas como:

• ¿Quién es esta persona?
• ¿Qué ha construido?
• ¿Qué le importa?
• ¿Puedo confiar en su criterio?
• ¿Qué debería hacer después?

Ese es el trabajo de la web.

La fuente de verdad está en el contenido estructurado. La web es una interfaz que lo presenta.

La capa de API

La API expone el mismo contenido principal como JSON estructurado.

Los endpoints importantes son:

GET /api/v1/me
GET /api/v1/projects
GET /api/v1/projects/:slug
GET /api/v1/products
GET /api/v1/products/:slug
GET /api/v1/notes
GET /api/v1/notes/:slug

Esta capa sirve al software que quiere consultar el sitio sin extraer datos de su interfaz.

Por ejemplo:

• un panel;
• una herramienta de reclutamiento;
• un índice de búsqueda;
• un script personal;
• un sistema de búsqueda con IA;
• una aplicación futura que consuma mi perfil como datos.

La API devuelve un formato de respuesta previsible con:

• api_version;
• ai_summary;
• meta;
• data.

El campo ai_summary está ahí a propósito. El software convencional puede usar data directamente. Los sistemas de IA pueden apoyarse en el resumen para entender qué significa la respuesta.

La capa de MCP

MCP expone los datos del sitio como herramientas que un agente puede llamar.

El servidor ofrece capacidades para que el agente no tenga que decidir por su cuenta qué URL consultar:

get_orlando_bio
get_projects
get_project
get_products
get_product
get_product_status
get_notes
get_note

Eso cambia la interacción. Una API expone recursos; MCP expone operaciones entre las que un agente puede elegir.

Por eso MCP encaja mejor que REST con ciertos flujos de los asistentes de IA. El modelo puede inspeccionar las herramientas disponibles, decidir cuál responde a la tarea, llamarla con argumentos estructurados y usar el resultado en su respuesta.

La capa de contenido

La fuente de contenido es sencilla a propósito.

Los proyectos, productos y notas viven en archivos estructurados. Tienen frontmatter para los metadatos y cuerpos MDX para los textos largos.

Eso permite una separación clara:

• el frontmatter alimenta las tarjetas, los filtros, las respuestas de la API y los resultados de las herramientas MCP;
• los cuerpos MDX alimentan las páginas de lectura;
• los campos de localización permiten traducir las interfaces que lo necesitan;
• los slugs proporcionan URL e identificadores de API estables.

Esta separación evita que la arquitectura se vuelva frágil. No quiero mantener una versión de un proyecto para la web, otra para la API y otra para MCP. Un único modelo de contenido debería alimentar todas las interfaces.

Validación del contenido

El contenido estructurado solo sirve si puedes confiar en su estructura.

El sitio valida campos como:

• título;
• slug;
• categoría;
• resumen;
• fecha de publicación;
• estado del proyecto;
• estado del producto;
• ruta de la captura;
• enlaces externos.

Las capas de API y MCP amplifican los errores.

Un slug incorrecto ya no causa solo un enlace roto. También puede producir una respuesta de API incorrecta, un resultado de herramienta que no sirve o una referencia confusa en un buscador.

La validación ayuda a mantener coherente la capa de contenido.

Manejo de errores

La API usa estructuras de error explícitas.

El objetivo es que los errores resulten comprensibles para el software y para las personas:

• una entrada inválida devuelve un error de validación;
• un recurso inexistente devuelve un error de recurso no encontrado;
• un exceso de peticiones devuelve información sobre el límite;
• un fallo inesperado devuelve un error interno controlado.

Los agentes también necesitan esa información. Si falla una llamada, deberían poder decidir si reintentar, pedir otro slug o explicar que el recurso solicitado no existe. Los fallos ambiguos complican esos flujos.

Versiones de la API

La API incluye el campo api_version.

La versión actual es sencilla: 1.0.0.

Ese campo existe porque una interfaz pública crea expectativas. Incluso una API personal pequeña se beneficia de las versiones cuando otras herramientas pueden consumirla.

Si cambio la estructura de las respuestas más adelante, quiero una vía clara:

• conservar v1 para los consumidores existentes;
• añadir campos sin romper los clientes anteriores;
• crear v2 solo cuando el contrato cambie de forma significativa.

Prepararse para el futuro consiste en dejar espacio para cambiar sin romper la confianza.

Caché de las respuestas

Los datos del sitio se leen con frecuencia y cambian despacio. Eso los hace adecuados para la caché.

La API pública puede almacenar durante periodos breves las respuestas de perfil, proyectos, productos y notas. Los cambios de contenido no necesitan reflejarse en milisegundos. Necesitan fiabilidad y rapidez.

La caché también evita carga innecesaria si las herramientas de IA o los rastreadores consultan los mismos endpoints repetidamente.

Es una de las razones prácticas para exponer datos estructurados: la interfaz resulta más fácil de almacenar en caché, entender y supervisar que la extracción de datos desde páginas.

Límites de seguridad

La decisión más importante de esta arquitectura es dónde trazar el límite de seguridad.

La API pública y las herramientas MCP deben exponer contexto público del sitio, sin dar acceso a operaciones privadas.

En este sistema significa:

• herramientas MCP de solo lectura;
• ninguna acción destructiva;
• ningún borrador;
• ningún secreto;
• ningún dato exclusivo de administración;
• límites de peticiones en los endpoints públicos;
• validación de todas las entradas.

No le des a un agente más poder del que necesita. Para un sitio personal, consultar contenido basta.

La arquitectura en una línea

El sitio es un único sistema de contenido con tres interfaces:

Content -> Website -> Humans
Content -> API -> Software
Content -> MCP -> Agents

El contenido llega a las personas mediante la web, al software mediante la API y a los agentes mediante MCP.

Me gustaría ver más sitios personales con contenido estructurado y trabajo que se pueda consultar directamente. Las personas ya usan herramientas para descubrir, evaluar y recordar a otros profesionales; el sitio también debería ser legible para esas herramientas.