Cómo documentar repositorios MCP de forma eficaz: manual práctico

Deja de perder colaboradores por READMEs vagos. Aquí tienes una receta práctica para documentar repositorios MCP correctamente.

Por qué la documentación MCP es distinta

Documentar un repositorio de Model Context Protocol (MCP) no es lo mismo que describir una API o una CLI típica. Estás explicando un contrato entre un cliente (a menudo un entorno de ejecución o IDE preparado para LLMs) y un servidor capaz de exponer herramientas, recursos, prompts y modelos mediante un protocolo coherente. La audiencia es variada: desarrolladores que integran tu servidor en clientes, mantenedores que lo amplían y revisores de seguridad que verifican flujos de datos y permisos. Una buena documentación debe cubrir tres capas:

Qué hace: capacidades y ejemplos de uso
Cómo funciona: versiones del protocolo, transportes, esquemas
Cómo confiar en él: seguridad, límites y modos de fallo

La única fuente de verdad: un README de primer nivel

Tu README es la puerta de entrada. Usa una estructura predecible para que la gente encuentre respuestas rápido. Un andamiaje probado:

Nombre y propósito
Fila de badges (licencia, CI, última release)
Resumen de compatibilidad (versión MCP, matriz de clientes)
Quickstart (instalar, ejecutar, verificar)
Configuración (env vars, ficheros, autenticación)
Capacidades (herramientas/recursos/prompts/modelos)
Ejemplos (peticiones y respuestas)
Desarrollo (ejecutar tests, lint, format)
Seguridad (permisos, salida de datos, secretos)
Resolución de problemas (errores comunes)
Versionado y changelog
Contribuir y código de conducta
Licencia

Una breve declaración de misión debe ir en la parte superior. Evita afirmaciones vagas. Deja claro qué desbloquea tu servidor o cliente MCP y quién debería usarlo.

Explica el contrato: protocolo y compatibilidad

Todo repositorio MCP debería declarar:

Versión de protocolo soportada (p. ej., MCP 1.2)
Soporte de características: herramientas, recursos, prompts, modelos, streaming, cancelación
Transporte(s): stdio, WebSocket, HTTP
Compatibilidad con clientes: qué clientes y versiones se prueban
Soporte de plataformas: Linux, macOS, Windows; CPU/ARM; soporte en contenedor

Detalla los cambios incompatibles y las deprecaciones. Si mantienes varias ramas para versiones del protocolo, documenta qué rama corresponde a qué versiones de cliente y cuánto tiempo soportarás cada línea.

Sé explícito sobre transportes y expectativas en tiempo de ejecución

MCP acepta distintos transportes; tu documentación debe especificar qué implementas realmente:

Stdio: cómo se lanza el proceso, enmarcado de I/O, cwd esperado
WebSocket: ruta de URL, subprotocolos, cabeceras de auth, recomendaciones TLS
HTTP: endpoints, content type, streaming, reglas CORS

Documenta límites de recursos y valores por defecto:

Tamaño máximo de petición
Tamaño y cadencia de fragmentos en streaming
Timeouts y settings de keepalive
Memoria/CPU recomendados para producción

Incluye una transcripción de handshake “hello world” por cada transporte para que los lectores vean los mensajes de apertura.

Capacidades: documenta herramientas, recursos, prompts y modelos

Trata cada capacidad como una mini-API con ejemplos y garantías.

Herramientas: nombre, descripción, JSON Schema para la entrada, formato de salida, efectos secundarios, idempotencia, perfil de latencia, límites de tasa, permisos requeridos
Recursos: reglas de descubrimiento, patrones de ruta, operaciones lectura/escritura soportadas, paginación o streaming
Prompts: marcadores, variables, valores por defecto, restricciones
Modelos: reglas de selección, opciones de sampling, límites de tokens, peculiaridades conocidas

Para las herramientas, favorece ejemplos con JSON Schema mostrando payloads mínimos y completos. Incluye al menos un ejemplo de error por herramienta, con indicaciones sobre reintentos o fallback.

Escribe JSON Schema como si importara

Los esquemas son documentación ejecutable. Hazlos claros y aplicables:

Dale a cada esquema un $id y versión en un directorio schemas/ dedicado
Usa $defs para tipos compartidos (p. ej., Pagination, FilePath, URL)
Proporciona ejemplos y valores por defecto
Usa format (uri, email, date-time) y pattern con responsabilidad
Restringe con minimum, maximum, minLength, maxLength
Explica las opciones enum en las descripciones
Documenta la posibilidad de null y las adiciones compatibles hacia atrás

Ejemplo:

{
	"$id": "https://example.org/schemas/tools/summarize.v1.json",
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"title": "summarize",
	"type": "object",
	"additionalProperties": false,
	"properties": {
		"text": {
			"type": "string",
			"minLength": 1,
			"description": "Plaintext to summarize."
		},
		"max_sentences": {
			"type": "integer",
			"minimum": 1,
			"maximum": 10,
			"default": 3,
			"description": "Cap the summary length."
		}
	},
	"required": ["text"],
	"examples": [{ "text": "Long article...", "max_sentences": 2 }]
}

Explica cómo versionas los esquemas y cómo el servidor elige la versión correcta.

Configuración: nombres, formatos y valores por defecto seguros

Reduce la conjetura con documentación de configuración explícita:

Variables de entorno: nombres, valores por defecto, ejemplos
Ficheros de config: ruta, formato (JSON/YAML/TOML), reglas de precedencia
Secretos: cómo proporcionarlos (env vars, gestores de secretos), nunca los comitees, consejos para desarrollo local
Perfiles: ajustes dev vs prod, toggles para logs verbosos, modos mock

Plantilla:

# .env
MCP_SERVER_PORT=8080
MCP_TRANSPORT=ws
MCP_ALLOWED_ORIGINS=https://localhost:3000
THIRD_PARTY_API_KEY=...
LOG_LEVEL=info

Documenta cómo se valida la configuración en el arranque y qué ocurre cuando es inválida.

Autenticación, autorización y ámbitos sensibles

Los revisores de seguridad necesitan respuestas precisas:

Qué secretos son necesarios (API keys, tokens OAuth)
Dónde se almacenan los tokens en memoria y en reposo
Qué scopes se solicitan y por qué
Cómo se muestra el consentimiento a los usuarios en los clientes
Destinos de egress de datos (dominios, puertos)
Recomendaciones de mínimo privilegio
Pasos para rotación y revocación

Si tu servidor puede realizar operaciones sobre archivos o llamadas de red en nombre del usuario, dilo alto y claro. Proporciona un mapa de permisos: capacidad → privilegios requeridos → avisos al usuario.

Ejemplos de uso que realmente funcionan

Muestra invocaciones concretas con clientes comunes o peticiones tipo curl para HTTP:

// tools/list response (excerpt)
{
	"tools": [
		{
			"name": "summarize",
			"description": "Create a short summary from longer text.",
			"input_schema": "https://example.org/schemas/tools/summarize.v1.json"
		}
	]
}

// tools/call request (excerpt)
{
	"name": "summarize",
	"arguments": { "text": "Article text...", "max_sentences": 2 }
}

Después muestra la respuesta correspondiente. Incluye una vía de error con una solución accionable.

Observabilidad: logs, métricas y tracing

La documentación debe enseñar a los usuarios a ver qué hace el servidor:

Formato de logs (JSON estructurado vs texto), niveles, reglas de redacción
IDs de petición y correlation IDs propagadas entre mensajes
Métricas (latencia por herramienta, tasas de error, profundidad de colas)
Tracing opcional (configuración OpenTelemetry, propagación de contexto)
Dónde van los logs por defecto y cómo redirigirlos

Proporciona una línea de comando para activar salida diagnóstica detallada para informes de errores.

_{Photo by Protagonist on Unsplash}

Rendimiento y límites

Haz que las expectativas de rendimiento sean predecibles:

Objetivos de latencia cold start y warm
Modelo de concurrencia y número de workers por defecto
Límites de tasa por herramienta y por usuario
Timeouts y políticas de reintento, tanto entrantes como salientes
Tamaños máximos de payload y comportamiento de back-pressure en streaming
Picos de memoria y puntos conflictivos conocidos

Añade una sección de “Dimensionamiento” con reglas prácticas para despliegues pequeños, medianos y grandes.

Modelo de errores y semántica de fallos

Los errores ambiguos minan la confianza. Estandariza:

Tipos de error con códigos estables y mensajes humanos
Qué errores son reintentables y el backoff recomendado
Éxitos parciales y cómo se señalan
Semántica de cancelación y qué limpieza ocurre
Garantías de idempotencia y deduplicación de peticiones

Mapea fallos internos a errores a nivel de protocolo de forma clara y consistente.

Estructura de ficheros y activos de documentación

Un repositorio ordenado enseña por su estructura. Considera:

README.md como punto de entrada
docs/ para guías (capabilities.md, security.md, transports.md)
schemas/ con JSON Schemas versionados y un README sobre la política de releases
examples/ con demos ejecutables y fixtures
tests/ pruebas de contrato que apunten al comportamiento del protocolo
.github/ con plantillas de PR, plantillas de issues, workflows
CHANGELOG.md para cambios legibles por humanos
CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md

Enlaza estos desde el README principal para que nada quede enterrado.

Desarrollo, pruebas y chequeos de contrato

Reduce la fricción de mantenimiento con estrategias de test documentadas:

Tests unitarios para handlers y validación de esquemas
Tests de contrato que ejerciten el handshake MCP y el descubrimiento de capacidades
Golden files para respuestas estables (cuando sea apropiado)
Tests de integración contra los clientes más usados
Fuzz tests para entradas guiadas por esquemas
Matriz de CI: SO, versiones de lenguaje, versiones del protocolo

Incluye comandos para ejecutar la suite completa localmente y una descripción de las puertas de CI.

Versionado, releases y migraciones

Usa SemVer y hazlo visible:

Cómo aumentas la versión para cambios a nivel de protocolo vs fixes internos
Cadencia de releases y cómo etiquetáis releases
Notas de release destacando deprecaciones, nuevas capacidades, pasos de migración
Política de deprecación con fechas y rutas de código
Checklist para release (tests, docs actualizados, IDs de esquema incrementados)

Fija rangos de dependencias para evitar roturas inesperadas y documenta versiones upstream incompatibles conocidas.

Política de seguridad y divulgaciones

Añade un SECURITY.md y enlázalo en el README:

Versiones soportadas para arreglos de seguridad
Cómo reportar vulnerabilidades (canales privados, ventana de respuesta)
Lenguaje de puerto seguro para investigación de buena fe
Instrucciones de escaneo de dependencias para contribuyentes
Guía de endurecimiento (sandboxing, aislamiento del sistema de ficheros, allowlists de salida)

Si tu servidor accede a ficheros o sistemas locales, documenta los valores por defecto del sandbox y cómo confinarlos.

Resolución de problemas que realmente soluciona

Una buena sección de troubleshooting es más que unos consejos. Para cada error común, documenta:

El mensaje exacto de error o el síntoma
Por qué ocurre
Cómo diagnosticarlo (comando, filtro de logs)
Cómo arreglarlo
Cómo prevenirlo en el futuro

Ejemplos:

“Client cannot discover tools” → URL de esquema no accesible; soluciona vendiendo los esquemas o activando CORS
“Schema mismatch error” → cliente con esquema en caché; limpia la caché o aumenta $id del esquema
“WebSocket disconnects” → timeout inactivo del proxy; aumenta el keepalive

Plantillas prácticas que puedes copiar

Ofrece plantillas en el repo que la gente pueda reutilizar y adaptar.

README boilerplate snippet:

# Project Name

Short purpose statement.

## Compatibility

- MCP version: 1.2
- Transports: stdio, ws
- Tested clients: ClientA vX, ClientB vY

## Quickstart

1. Install...
2. Run...
3. Verify with tools/list...

Las plantillas de issues para informes de bugs deberían pedir la versión del protocolo, transporte, logs y pasos mínimos de reproducción.

Documenta el flujo humano, no solo el código

La gente mantiene tu repositorio MCP. Explica:

Cómo configurar un entorno de desarrollo desde cero
Cómo ejecutar una capacidad aislada
Cómo preparar un cambio de esquema y cortar un pre-release
Quién revisa qué y en qué orden
Cómo obtener una cuenta de prueba para servicios de terceros

Una pequeña “Guía del Mantenedor” en docs/ se amortiza rápidamente.

Mantén la documentación sincronizada con automatización

La documentación desactualizada es peor que no tenerla. Añade automatización:

Chequeo en CI que falle si los esquemas cambian sin actualizar docs
Script que genere un catálogo de herramientas a partir de los esquemas
Checklist de cobertura de docs en la plantilla de PR
Comprobadores de enlaces y validadores de esquemas integrados en CI
Job periódico que ejecute smoke tests de compatibilidad con clientes

Pequeños bots pueden reconstruir examples/ cuando los esquemas o handlers evolucionan.

Accesibilidad y claridad para audiencias mixtas

Como MCP se sitúa en el límite entre herramientas LLM y stacks de software clásicos, no asumas conocimientos previos. Explica la jerga una vez. Añade diagramas que muestren:

Flujo Cliente ↔ transporte ↔ servidor
Prompts de permisos y rutas de datos
Ciclo de vida desde el handshake hasta el teardown

Usa encabezados claros, párrafos cortos y pasos numerados. Cuando existan opciones, indica cuál recomiendas y por qué.

Checklist listo para release

Antes de etiquetar una release, confirma que la documentación esté realmente publicable:

README actualizado con versión y compatibilidad
Esquemas nuevos o cambiados llevan nuevos valores de $id
Ejemplos verificados contra el build de release
Cambios de seguridad registrados en SECURITY.md
Entradas en CHANGELOG con notas de migración
Badges de CI en verde y enlaces funcionales
Plantillas de issues y PR reflejan el flujo actual

En caso de duda, añade una guía de migración de un párrafo por release que toque cambios de protocolo, bumps de esquema y cambios de comportamiento.

Únelo todo

Un repositorio MCP es un contrato vivo. Documenta el contrato primero y luego el código. Haz que cada capacidad sea descubrible, cada esquema aplicable y cada fallo diagnosable. Si un nuevo colaborador puede clonar, ejecutar y verificar tu servidor en 10 minutos sin preguntar, tu documentación hace bien su trabajo. Ahora implementa la checklist, conecta la automatización para mantenerla honesta y publica documentación que genere confianza.

External Links

How to Write Effective Documentation for Your MCP Server Projects How to use MCP servers to generate docs - Mintlify read-docs-mcp | MCP Servers - LobeHub GitMCP - an instant MCP server for any GitHub repo documentation MCP Integration: Streamlining Multi-Repo Development