Guía práctica para metadatos y versionado de repositorios MCP

No puedes confiar en lo que no puedes describir, y no puedes actualizar lo que no puedes versionar. Los repositorios MCP viven o mueren por esos dos hechos.

Esta guía recorre cómo estructurar los metadatos y el versionado en los repositorios Model Context Protocol (MCP) para que herramientas, modelos y humanos puedan depender de ellos—de forma segura y predecible.

1. Por qué importan los metadatos de un repositorio MCP

Un repositorio MCP es más que un cubo de código. Es un catálogo de capacidades utilizable por máquina: herramientas, recursos, prompts, esquemas y configuración que un modelo o una capa de orquestación puede cargar bajo demanda.

Los metadatos son cómo respondes tres preguntas fundamentales, programáticamente y de forma fiable:

¿Qué es esto?
¿Puedo confiar en ello?
¿Es compatible con mi entorno y versión?

Si tus metadatos son débiles o inconsistentes, te enfrentarás a:

Herramientas que aparecen en un entorno y desaparecen en otro.
Cambios incompatibles enviados como “actualizaciones menores”.
Duplicación confusa (“¿Cuál github-search es la actual?”).
Fallos difíciles de depurar cuando clientes de modelo cargan o actualizan repositorios MCP automáticamente.

Invertir en metadatos y versionado consistentes y explícitos hace que el resto de tu trayectoria MCP sea sobrevivible.

2. La superficie central de metadatos de un repositorio MCP

Aunque las implementaciones evolucionarán, cualquier repositorio MCP serio debería estandarizar un archivo de metadatos de primer nivel—a menudo algo como:

mcp.json
mcp.config.json
mcp.yaml
o un formato de configuración canónico similar.

Como mínimo, este archivo debería abarcar:

Identidad del repositorio.
Versionado y compatibilidad.
Propiedad y confianza.
Capacidades.
Pistas de distribución e instalación.

Desgranémoslo.

2.1 Identidad: nombrar las cosas para que no duelan después

Los metadatos de identidad deberían resultar aburridos. Eso es bueno. Deben incluir:

id: un identificador estable y amigable para máquinas
- Example: "id": "com.acme.mcp.github"
- Trátalo como inmutable una vez publicado.
name: etiqueta legible por humanos
- Example: "name": "Acme GitHub MCP Tools"
description: explicación breve, precisa y no comercial
- Example: "description": "Tools for querying repositories, issues, and pull requests via GitHub's REST and GraphQL APIs."
homepage o docs: dónde puede ir un humano para aprender más
- Example: "homepage": "https://acme.dev/mcp/github"

Usa IDs globalmente únicos, estilo reverse-DNS, cuando sea posible (similar a paquetes Java o IDs de apps Android). Esto evita colisiones cuando varios proveedores publican repositorios con nombres parecidos.

2.2 Propiedad, contacto y señales de confianza

Si un cliente de modelo descubre MCP repositorios automáticamente, necesita pistas sobre quién respalda este código:

publisher: organización o individuo
- "publisher": "Acme Corp"
contact: contacto de soporte o seguridad
- "contact": "security@acme.dev"
license: identificador SPDX o referencia clara al texto de la licencia
- "license": "Apache-2.0"
source: repositorio fuente canónico
- "source": "https://github.com/acme/mcp-github"

Puedes ir más allá con:

signingKeys: claves públicas para firmas del repositorio.
verification: referencias a logs de transparencia o servicios de firma.
securityPolicy: enlace a una política de seguridad o página de avisos.

Estos campos permiten que la infraestructura haga cumplir políticas como:

“Solo usar repositorios MCP firmados por claves que confiamos.”
“Solo auto-instalar repositorios de editores en una lista de permitidos.”

2.3 Plataforma, runtime y compatibilidad con modelos

Los repositorios MCP a menudo dependen de un runtime (Node, Python, Docker, serverless) y pueden asumir características o límites de tamaño para el contexto del modelo.

Proporciona metadatos de compatibilidad claros:

{
  "runtime": {
    "type": "node",
    "version": ">=18.0.0"
  },
  "mcp": {
    "protocolVersion": ">=1.1.0 <2.0.0",
    "features": ["tools", "resources", "events"]
  },
  "models": [
    {
      "pattern": "gpt-4.*",
      "constraints": {
        "maxContextTokens": 128000,
        "supportsStreaming": true
      }
    }
  ]
}

Ideas clave:

Compatibilidad con runtime
- type: p. ej. node, python, docker, binary, http.
- version: rango o versión mínima.
Compatibilidad con el protocolo MCP
- Usa rangos (p. ej. >=1.1.0 <2.0.0) en lugar de una única versión fija.
Pistas sobre modelos
- No son requisitos estrictos, sino guías para los orquestadores:
  - Tamaño mínimo de contexto para uso seguro.
  - Si las herramientas requieren streaming o modo JSON.
  - Cualquier incompatibilidad conocida.

Esto desbloquea una planificación más inteligente:

Las herramientas pueden decidir no cargar un repositorio pesado cuando se usa un modelo de contexto pequeño.
Los gateways pueden advertir: “Este repositorio MCP puede superar la ventana de contexto de tu modelo.”

3. Estructurar los metadatos de capacidades

Un repositorio es un paquete de capacidades. Para MCP, normalmente se clasifican en:

Tools
Resources
Config / settings
Servicios de fondo opcionales o feeds de eventos

Los metadatos deben hacer que cada capacidad sea descubrible, tipada y explicable tanto para modelos como para operadores.

3.1 Herramientas: contratos de entrada/salida a la vista

Cada herramienta en tu repositorio debería tener una descripción legible por máquina. En estilo JSON Schema, algo así:

{
  "tools": [
    {
      "name": "search_issues",
      "version": "1.2.0",
      "description": "Search GitHub issues by repository, labels, and status.",
      "inputSchema": { /* JSON Schema */ },
      "outputSchema": { /* JSON Schema */ },
      "examples": [
        {
          "summary": "Find open bugs labeled 'priority: high'",
          "input": {
            "repo": "acme/mcp-github",
            "labels": ["bug", "priority: high"],
            "state": "open"
          }
        }
      ],
      "rateLimits": {
        "perMinute": 30,
        "burst": 10
      },
      "auth": {
        "type": "oauth2",
        "scopes": ["repo", "read:org"]
      },
      "deprecated": false,
      "replacedBy": null
    }
  ]
}

Piezas importantes:

name: identificador estable de la herramienta dentro del repositorio.
version: versión semántica por herramienta (más sobre esto después).
inputSchema / outputSchema: definición de esquema estricta y validada.
examples: pistas canónicas de uso; a los modelos y a las herramientas de evaluación les encantan.
rateLimits: para que los orquestadores puedan regular las llamadas.
auth: qué secretos o scopes son necesarios.
deprecated / replacedBy: migraciones suaves en lugar de eliminaciones sorpresivas.

3.2 Recursos: datos, archivos y streams

Los recursos abarcan cosas como:

Bases de conocimiento.
Archivos de configuración.
Raíces de sistema de ficheros.
Índices remotos.

Describe cada recurso con:

{
  "resources": [
    {
      "id": "kb.product_docs",
      "name": "Product Documentation",
      "description": "Indexed product docs with sections and change history.",
      "type": "search-index",
      "format": "markdown",
      "location": "s3://acme-docs-index/prod",
      "version": "2025.10.3",
      "access": {
        "requiresAuth": true,
        "allowedRoles": ["support", "engineering"]
      }
    }
  ]
}

Puntos clave:

Usa IDs lógicos (kb.product_docs) que permanezcan constantes incluso si la infraestructura de respaldo cambia.
Distingue entre versión del recurso y versión del repositorio.
Captura las suposiciones de control de acceso: muchos clientes MCP necesitarán respetarlas.

3.3 Configuración y ajustes

Los operadores necesitan ver qué espera el repositorio de su entorno. Piensa en:

Claves API y secretos.
Flags de características opcionales.
Configuración por inquilino.

Representa esto en metadatos estructurados:

{
  "config": {
    "required": [
      {
        "key": "GITHUB_TOKEN",
        "description": "GitHub personal access token with repo and read:org scopes.",
        "type": "string",
        "secret": true
      }
    ],
    "optional": [
      {
        "key": "DEFAULT_ORG",
        "description": "Fallback organization for repository discovery.",
        "type": "string",
        "secret": false,
        "default": "acme"
      }
    ]
  }
}

Esto permite:

Generación automática de UI para pantallas de configuración.
Comprobaciones previas a la carga del repositorio.
Manejo de secretos más seguro (no más “mete todo en un .env y cruzar los dedos”).

4. Diseñar una estrategia de versionado que resista

Ahora la parte que te salva del caos de las actualizaciones: versionado.

Los desarrolladores instintivamente recurren a semantic versioning (SemVer). Eso es un buen comienzo, pero los repositorios MCP tienen algunos matices:

Hay una versión del repositorio y a menudo versiones por herramienta.
Los clientes pueden auto-actualizar sin intervención humana.
Los modelos dependen de contratos inferidos a partir de ejemplos y comportamiento previo.

4.1 Las tres capas de versión

Piensa en tres capas:

Versión del repositorio
- Versión global del paquete.
- Ejemplo: "version": "1.4.0".
Rango de compatibilidad de protocolo
- "mcp.protocolVersion": ">=1.1.0 <2.0.0".
Versiones de herramientas/recursos
- Cada herramienta o recurso importante puede tener su propio version.

La versión del repositorio debería seguir las reglas SemVer impulsadas por el cambio visible al cliente:

MAJOR: cambios incompatibles en:
- Nombres de herramientas o eliminación de herramientas antes estables.
- Esquemas de entrada/salida de forma incompatible hacia atrás.
- Requisitos de autenticación (p. ej. eliminar un método de auth soportado).
- Contratos de comportamiento críticos (p. ej. “esta herramienta ya no devuelve salida por streaming donde antes lo hacía”).
MINOR: añadidos compatibles hacia atrás:
- Nuevas herramientas.
- Nuevos campos opcionales en esquemas.
- Mejoras de rendimiento que no alteran el contrato.
PATCH: correcciones de errores que no afectan esquema ni semántica:
- Corregir un bug que antes provocaba fallos con entradas válidas.
- Corregir documentación y ejemplos.
- Ajustar la validación para que coincida con el comportamiento documentado.

4.2 Cuándo ayuda el versionado a nivel de herramienta

El versionado por herramienta es valioso cuando:

Soportas automatización a largo plazo que fija una versión concreta de la herramienta.
Prevés múltiples variantes de una herramienta conviviendo lado a lado.

Patrones que funcionan:

Usa tool.version como un contrato semántico solo para la API de esa herramienta.
Mantén la version del repositorio para el paquete en su conjunto.
Permite que los clientes soliciten:
- “Cargar search_issues versión 1.x” o
- “Cualquier search_issues compatible con la versión ^1.2.0”.

Esto te da flexibilidad para:

Experimentar con search_issues 2.0.0 mientras mantienes 1.x estable.
Fomentar migraciones graduales en lugar de actualizaciones forzosas masivas.

5. Contratos estables: esquema y comportamiento

Los números de versión solo significan algo si siguen contratos reales y estables.

5.1 Cambios de esquema hacia adelante y hacia atrás compatibles

Sigue algunas reglas básicas:

Compatibles hacia atrás (seguros para MINOR):
- Añadir un nuevo campo opcional con un valor por defecto.
- Ampliar un enum con un nuevo valor si los llamantes pueden ignorarlo.
- Extender oneOf o anyOf de manera no rompedora.
Incompatibles hacia atrás (requieren MAJOR):
- Renombrar o eliminar campos usados por los llamantes.
- Endurecer la validación de modo que cargas válidas antes ahora fallen.
- Cambiar tipos de campo (p. ej. string a array).

Documenta esto explícitamente en tus metadatos:

{
  "changelog": [
    {
      "version": "1.3.0",
      "date": "2026-02-10",
      "changes": [
        {
          "type": "schema",
          "scope": "tool:search_issues",
          "compatibility": "backward-compatible",
          "description": "Added optional 'assignee' field to filter issues by assignee."
        }
      ]
    }
  ]
}

Aunque no todos los clientes lean el changelog, es invaluable para operadores humanos y QA automatizado.

5.2 Contratos de comportamiento más allá del esquema

El esquema no es suficiente. También tienes garantías de comportamiento:

Ordenación de resultados.
Límites y timeouts por defecto.
Manejo de errores y semánticas de reintento.
Idempotencia.

Define esto en algún lugar legible por máquina o al menos documentado de forma estable:

{
  "behavior": {
    "search_issues": {
      "ordering": "sorted by updated_at descending by default",
      "defaultLimit": 50,
      "maxLimit": 200,
      "idempotent": true,
      "timeoutMs": 10000,
      "retries": {
        "max": 2,
        "backoff": "exponential"
      }
    }
  }
}

Cuando cambies esto de forma que importe a los clientes (por ejemplo, reduces drásticamente timeoutMs o cambias el orden por defecto), trátalo como un cambio de contrato y versiona en consecuencia.

6. Metadatos de dependencias y composición

Los repositorios MCP dependerán cada vez más unos de otros. Por ejemplo:

Un repositorio “sales assistant” depende de:
- Herramientas CRM.
- Búsqueda en docs de producto.
- Directorio de RRHH para la propiedad de cuentas.

Deberías exponer metadatos de dependencia para evitar una red oculta de importaciones frágiles.

6.1 Describir dependencias explícitamente

Usa una estructura similar a los gestores de paquetes:

{
  "dependencies": {
    "com.acme.mcp.crm": "^2.0.0",
    "com.acme.mcp.product_docs": "~1.3.0"
  },
  "optionalDependencies": {
    "com.acme.mcp.hr_directory": ">=1.0.0 <2.0.0"
  },
  "peerDependencies": {
    "com.acme.mcp.auth": "^1.1.0"
  }
}

Dónde:

dependencies: repositorios que deben estar presentes para la funcionalidad completa.
optionalDependencies: repositorios que pueden mejorar el comportamiento pero no son necesarios.
peerDependencies: repositorios que se espera que el entorno anfitrión proporcione (p. ej. una capa de auth compartida).

Los orquestadores conscientes del modelo pueden entonces:

Comprobar dependencias faltantes pronto.
Sugerir instalar peers requeridos.
Evitar cargar combinaciones incompatibles.

6.2 Metadatos transitivos y aplanamiento

Si encadenas varios repositorios, sus grafos de dependencia pueden crecer rápidamente.

Buenas prácticas:

Mantén las dependencias de primer nivel cortas y claramente justificadas.
Divide repositorios monolíticos en paquetes MCP más pequeños y focalizados cuando las dependencias se disparen.
Considera proporcionar un repositorio “meta” que agregue otros de bajo nivel:
- Por ejemplo, com.acme.mcp.sales_suite que dependa de varios repositorios MCP específicos y exponga un conjunto curado de herramientas.

7. Publicación, descubrimiento e indexado de metadatos

Una vez que tus metadatos están estructurados, necesitas exponerlos de maneras que las herramientas puedan descubrir.

7.1 Ubicaciones y endpoints estándar

Patrones comunes:

Archivo manifiesto estático en la raíz del repositorio:
- mcp.json o mcp.yaml.
URL well-known para repositorios remotos:
- https://example.com/.well-known/mcp.json.
Endpoint de descubrimiento HTTP:
- GET /mcp/manifest que devuelve metadatos JSON.

Asegura que:

El manifiesto sea cacheable (con ETags, Last-Modified o URLs versionadas).
El manifiesto incluya hashes de contenido o firmas para integridad si es posible.

7.2 Indexes centrales vs catálogos locales

Los entornos probablemente mantendrán:

Un índice central (como npm o PyPI para MCP).
Catálogos empresariales con repositorios aprobados y curados.

Haz que tus metadatos sean amigables para índices:

Proporciona descripciones cortas y claras.
Incluye categorías o tags:
- "categories": ["developer-tools", "code-search", "issue-tracking"]
Expón una vista “card” mínima:
- ID, name, publisher, última actualización, capacidades clave.

Las herramientas de descubrimiento podrán entonces mostrar:

“Todos los repositorios MCP que ofrecen herramientas code_search.”
“Solo repositorios MCP que soportan protocolo >=1.2.0.”

_{Photo by NASA on Unsplash}

8. Gestionar actualizaciones en el mundo real

Los números de versión en papel son fáciles. Los entornos vivos llenos de automatizaciones y usuarios humanos no lo son.

Necesitas patrones operativos que respeten metadatos y versionado.

8.1 Pinning, rangos y auto-actualizaciones

Los clientes y orquestadores deberían soportar:

Versiones fijadas: versión exacta, p. ej. 1.2.3.
Rangos de versión: ^1.2.0, ~1.3.0, >=2.0.0 <3.0.0.
Canales: stable, beta, canary.

Considera una configuración como:

{
  "repositories": [
    {
      "id": "com.acme.mcp.github",
      "version": "^1.3.0",
      "channel": "stable",
      "autoUpdate": true
    }
  ]
}

Compensaciones:

Fijar versiones ofrece máxima seguridad pero no actualizaciones de seguridad ni correcciones.
Los rangos permiten actualizaciones automáticas y controladas dentro de una versión mayor.
Los canales permiten probar nuevas versiones en cargas de trabajo limitadas primero.

8.2 Ventanas de deprecación y políticas de retirada

Romper un contrato de la noche a la mañana es una forma rápida de perder la confianza en tu ecosistema MCP.

Incluye:

Flags de deprecación en los metadatos:

{
  "deprecated": true,
  "deprecationDate": "2026-05-01",
  "sunsetDate": "2026-08-01",
  "migrationGuide": "https://acme.dev/mcp/github/migration-1.x-to-2.x"
}

Comunicación por adelantado sobre:
- Qué herramientas o endpoints desaparecerán.
- Qué reemplazos existen.
- Cómo cambiará el comportamiento.

Usa metadatos para permitir que las herramientas advertir:

“Este repositorio MCP dejará de estar disponible en 45 días; actualiza a 2.x.”

8.3 Rollbacks y releases seguros

Cuando una nueva versión se comporta mal, necesitas una forma sencilla de volver atrás.

Sugerencias:

Mantén metadatos y artefactos antiguos accesibles durante una ventana de retención definida.
Marca los releases claramente (v1.4.0, v1.4.0-hotfix1).

Usa campos de metadatos como:

{
  "status": "stable", // other values: "beta", "deprecated", "withdrawn"
  "replacedByVersion": "1.4.1"
}

Si debes retirar un release:

Márcalo como "status": "withdrawn" en el índice.
Actualiza rápidamente los endpoints de descubrimiento.
Proporciona notas de remediación (p. ej. “No usar 1.4.0 para jobs por lotes; actualiza a 1.4.1”).

9. Seguridad, integridad y auditabilidad

Los repositorios MCP están en la intersección de automatización y sistemas externos. Los metadatos de seguridad no son opcionales.

9.1 Firmado y metadatos de integridad

Proporciona campos que permitan a los clientes validar lo que descargan:

{
  "integrity": {
    "manifestHash": "sha256-...",
    "signedBy": [
      {
        "keyId": "acme-mcp-signing-1",
        "signature": "base64-..."
      }
    ],
    "signingCertificates": [
      "https://acme.dev/keys/mcp-signing-1.pem"
    ]
  }
}

Esto soporta:

Validación de cadena de confianza.
Políticas como “solo cargar repositorios firmados por estas claves”.

9.2 Permisos y metadatos de acceso a datos

Para entornos que tratan datos sensibles, describe:

Categorías de datos a los que accede:
- "dataCategories": ["source-code", "customer-data", "billing"]
Suposiciones de residencia de datos:
- "dataResidency": ["eu-west-1", "us-east-1"]
Comportamiento de logging:
- "logs": { "storesPayloads": false, "retentionDays": 30 }

Esto permite a los equipos de seguridad aplicar:

“No cargar repositorios MCP que manejen customer-data en este sandbox.”
“Solo repositorios con residencia de datos EU para cargas EU.”

9.3 Pistas de auditoría e historial de cambios

Mantén un log de auditoría append-only de:

Cambios en metadatos.
Versiones publicadas y sus hashes.
Avisos de seguridad.

Incluso un archivo simple en JSON (mcp.history.json) es una gran mejora para:

Forense (“¿qué versión se cargó en el momento del incidente X?”).
Documentación de cumplimiento.
Depuración de regresiones.

10. Una plantilla mínima y coherente de metadatos

Juntando todo, aquí tienes una plantilla compacta que cubre lo esencial sin ser inmanejable:

{
  "id": "com.acme.mcp.github",
  "name": "Acme GitHub MCP Tools",
  "description": "Tools for searching and managing GitHub repositories, issues, and pull requests.",
  "version": "1.3.0",
  "publisher": "Acme Corp",
  "contact": "support@acme.dev",
  "license": "Apache-2.0",
  "homepage": "https://acme.dev/mcp/github",
  "source": "https://github.com/acme/mcp-github",

  "mcp": {
    "protocolVersion": ">=1.1.0 <2.0.0",
    "features": ["tools", "resources"]
  },

  "runtime": {
    "type": "node",
    "version": ">=18.0.0"
  },

  "tools": [
    {
      "name": "search_issues",
      "version": "1.2.0",
      "description": "Search GitHub issues with flexible filters.",
      "inputSchema": { "$ref": "./schemas/search_issues_input.json" },
      "outputSchema": { "$ref": "./schemas/search_issues_output.json" },
      "deprecated": false
    }
  ],

  "resources": [
    {
      "id": "kb.repo_readme_cache",
      "name": "Repository README Cache",
      "type": "document-store",
      "format": "markdown",
      "location": "s3://acme-mcp/github-readmes/prod",
      "version": "2026.02.01"
    }
  ],

  "config": {
    "required": [
      {
        "key": "GITHUB_TOKEN",
        "description": "GitHub token with repo and read:org scopes.",
        "type": "string",
        "secret": true
      }
    ]
  },

  "dependencies": {
    "com.acme.mcp.auth": "^1.1.0"
  },

  "categories": ["developer-tools", "code", "github"],
  "tags": ["github", "issues", "repos"],

  "integrity": {
    "manifestHash": "sha256-...",
    "signedBy": []
  }
}

Puedes extender esta plantilla a medida que tu ecosistema madure, pero incluso esta base entrega:

Identidad clara.
Compatibilidad honesta.
Capacidades descubribles.
Un buen punto de partida para la automatización consciente de versiones.

11. Recomendaciones prácticas para adoptar hoy

Para cerrar, aquí tienes pasos concretos para poner orden en los metadatos y el versionado de tus repositorios MCP:

Elige un formato de manifiesto canónico
- Decide mcp.json (o similar) y cúmplelo.
Define un esquema de IDs de repositorio
- Reverse-DNS, único por repositorio, inmutable tras publicación.
Aplica reglas de semantic versioning
- Documenta qué cuenta como MAJOR/MINOR/PATCH en tu organización.
Exige metadatos de esquema para cada herramienta
- Esquemas de entrada/salida; validar en CI.
Rastrea versiones por herramienta solo cuando haga falta
- No compliques en exceso salvo que necesites variantes lado a lado.
Expone dependencias y rangos de compatibilidad
- Versiones del protocolo MCP, runtimes y dependencias del repositorio.
Implementa campos de deprecación y ventanas de retirada
- Nunca elimines herramientas sin aviso y guía de migración.
Firma manifiestos o al menos hasheálos
- Prepárate para políticas de seguridad más estrictas en el futuro.
Integra comprobaciones de metadatos en CI
- Lint de manifiestos, validar esquemas, exigir bumps de versión por cambios de contrato.
Publica un changelog conciso por release
- Enlázalo desde los metadatos para que humanos y herramientas lo encuentren rápido.

Haz esto de forma consistente y tus repositorios MCP serán más fáciles de descubrir, más seguros de actualizar y más confiables por cada modelo y plataforma que dependa de ellos.

External Links

Registry FAQ - Model Context Protocol （MCP） awesome-mcp-servers/docs/version-control.md at main - GitHub How to MCP - The Complete Guide to Understanding Model Context … What is MCP Registry? Architecture, Benefits & Setup Guide A Developer’s Guide to the MCP - Zep