Guía para desarrollar extensiones personalizadas de MCP: desde la estructura del repositorio hasta el lanzamiento

Las extensiones MCP personalizadas convierten a un asistente genérico en un especialista que puede hacer trabajo en tus sistemas: de forma segura, repetible y con medidas de contención.

Lo que “extensión MCP” realmente significa en repositorios MCP

En repositorios MCP, una “extensión” suele ser una de dos cosas:

1. Un servidor MCP independiente que publicas (o mantienes privado) y que expone capacidades —herramientas, recursos y prompts— a través del Model Context Protocol.
2. Un módulo/paquete del repositorio que ayuda a construir, configurar o desplegar servidores MCP (por ejemplo, una librería de handlers de autenticación compartidos, validación de esquemas o plantillas de despliegue).

La mayoría de los equipos se refieren a lo primero: un servidor MCP personalizado que añade capacidades específicas del dominio, como “consultar el inventario del almacén”, “abrir un ticket en Jira”, “generar un informe de compliance” o “resumir las llamadas de clientes de la semana pasada”.

MCP es intencionalmente simple a nivel de protocolo, pero las extensiones del mundo real implican un diseño cuidadoso: alcance, autenticación, salidas predecibles, manejo de errores y documentación que haga la extensión usable por humanos y modelos.

Empieza por el diseño de la capacidad (antes de escribir código)

La forma más rápida de crear una extensión desordenada es empezar por implementar endpoints. La forma más rápida de crear una extensión fiable es empezar con el diseño de capacidades.

Decide qué vas a exponer: herramientas vs recursos vs prompts

Los servidores MCP pueden exponer tres tipos de capacidad principales:

• Tools (herramientas): funciones invocables que hacen algo. Ejemplos: create_ticket, search_docs, run_sql_readonly.
• Resources (recursos): datos estructurados que se pueden obtener y referenciar. Ejemplos: un árbol de archivos, un artículo de base de conocimiento, el registro de un cliente.
• Prompts: plantillas de prompt reutilizables que guían al modelo de forma consistente para tareas comunes.

Una heurística práctica:

• Si cambia el estado o desencadena una acción: tool.
• Si es principalmente “leer y citar”: resource.
• Si es “repetir este flujo de trabajo con frecuencia”: prompt.

Reduce la superficie de exposición

Los mantenedores de extensiones a menudo sobreestiman cuántas herramientas necesitan. Empieza con menos herramientas, robustas y componibles.

Patrón malo:

• create_ticket_bug
• create_ticket_task
• create_ticket_incident

Patrón mejor:

• create_ticket con un campo type limitado, validado en el servidor.

Tu yo futuro te lo agradecerá cuando tengas que añadir logging, límites de cuota o comprobaciones de permisos: una vez, no tres.

Escribe “contratos de herramienta” en serio

Antes de implementar, redacta una página por contrato para cada herramienta:

• Name: estable, lower_snake_case
• Purpose: una frase
• Inputs: esquema con tipos y restricciones
• Outputs: esquema con ejemplos
• Error modes: fallos típicos y mensajes
• Security: scopes requeridos, redacciones, requisitos de auditoría
• Idempotency: qué ocurre si la herramienta se llama dos veces

Trata estos contratos como parte de tu repo. En muchos repositorios MCP, estos documentos se convierten en tu activo de mantenimiento a largo plazo.

Elige una arquitectura de extensión que no te atrape después

Normalmente implementarás un servidor MCP como un servicio pequeño que habla MCP sobre stdio o HTTP (dependiendo de tu stack y cliente). Independientemente del transporte, quieres una estructura que soporte:

• Añadir herramientas sin dispersar archivos
• Autenticación y políticas centralizadas
• Validación compartida y formato de errores
• Salidas deterministas
• Pruebas sin credenciales reales

Una maqueta limpia de repo para extensiones MCP

Una disposición ampliamente práctica:

• src/
  • server/ (cableado MCP, registro, transporte)
  • tools/ (un archivo por herramienta o por dominio)
  • resources/ (handlers de recursos)
  • prompts/ (plantillas de prompt + metadatos)
  • lib/ (auth, clientes, validación, redacción, logging)
• tests/
  • unit/
  • integration/
  • fixtures/
• docs/
  • tools.md
  • resources.md
  • prompts.md
  • security.md
  • changelog.md
• examples/ (scripts mínimos que muestran uso local)
• mcp.json o plantilla de config (si tu ecosistema lo usa)

Esta estructura se mapea limpiamente a cómo se consumen las capacidades MCP: tools/resources/prompts son descubribles, y tu lógica de políticas y glue permanece centralizada.

Haz que el “camino feliz” sea aburrido

Una extensión debe comportarse de forma predecible incluso cuando el modelo está siendo… creativo.

Apunta a:

• Validación estricta de entradas (rechazar campos desconocidos)
• Salidas normalizadas (claves estables, tipos estables)
• Forma de error consistente (amigable para máquinas)
• Mensajes claros de “qué hacer a continuación” para fallos recuperables

Implementación de herramientas: patrones prácticos que funcionan

Las herramientas son donde la mayoría de las extensiones MCP personalizadas demuestran su valor. También donde suelen romperse.

Define esquemas y valídalos en el servidor

Aunque tu cliente valide, el servidor debe validar de nuevo. Trata todo como entrada no fiable.

Restricciones comunes que merece la pena aplicar:

• Límites de longitud en strings (nombres, títulos, descripciones)
• Restricciones enum (priority: low/medium/high)
• Restricciones regex (claves de ticket, IDs de cliente)
• Tamaños máximos de arrays (para evitar explosiones de payload)
• Formatos de fecha (solo ISO 8601, por sentido común)

Si tu stack soporta JSON Schema o un validador tipado, úsalo y falla rápido.

Devuelve salidas que los modelos puedan reutilizar con fiabilidad

Los modelos funcionan mejor con:

• JSON plano cuando sea posible
• IDs estables
• Campos de estado explícitos
• URLs cuando proceda
• Poca prosa en campos destinados a uso programático

Ejemplo de forma de salida para una herramienta de acción:

• status: success | failed
• id: ID del objeto creado
• url: deep link
• summary: línea corta legible por humanos
• next_actions: array opcional de seguimientos recomendados

Evita volcar respuestas crudas de APIs a menos que también proporciones una vista normalizada.

Implementa un sobre de error estándar

Un sobre de error consistente hace tu extensión más fácil de depurar y más segura de automatizar. Un buen sobre incluye:

• error_code (estable, fácil de buscar)
• message (legible por humanos)
• details (estructurado, opcional)
• retryable (booleano)
• suggested_fix (sugerencia corta)

Cuando un modelo se encuentra con un error, puede decidir si reintentar, pedir datos faltantes o detenerse.

Añade límites de tasa y timeouts desde el principio

Incluso las extensiones internas pueden accidentalmente DDoS sistemas internos si se invocan repetidamente. Pon medidas de contención desde el día uno:

• Timeouts por herramienta (p. ej., 10–30 segundos)
• Políticas de reintento con backoff (cuidado con herramientas no idempotentes)
• Límites de tasa en el servidor (por usuario/token)
• Circuit breakers para caídas de downstream

Implementación de recursos: haz los datos referenciables, no solo recuperables

Los recursos están infravalorados. Un buen diseño de recursos ayuda al modelo a citar y navegar información sin convertir tu servidor en un “proveedor de blobs de texto gigante”.

Prefiere recursos pequeños y enlazables

En lugar de un recurso llamado company_handbook, considera:

• handbook/index
• handbook/{section_id}
• handbook/search?q=...

Esto permite al modelo traer solo lo que necesita y reduce el gasto de tokens.

Incluye metadatos para trazabilidad

Las respuestas de recursos deberían incluir:

• Un identificador de recurso estable
• Timestamps de última actualización (si es posible)
• Enlaces a la fuente o IDs canónicos
• Nivel de acceso (public/internal/restricted)
• Extractos opcionales más una ruta para obtener el contenido completo

La trazabilidad importa para cumplimiento y para depurar “¿de dónde vino esa respuesta?”

Prompts: el silencioso caballo de batalla de las grandes extensiones

Los prompts en MCP no son solo “un texto útil”. Son flujos de trabajo repetibles que envías con tu extensión para que el asistente se comporte de forma consistente.

Plantillas de prompt útiles incluyen:

• “Draft a support reply in our tone”
• “Summarize a ticket for an engineer”
• “Generate release notes from merged PR titles”
• “Convert raw query results into an executive brief”

Una plantilla de prompt sólida tiene:

• Un rol y objetivo claros
• Inputs requeridos
• Un formato de salida estructurado
• Guardrails (“Si faltan datos, pídelos”)
• Guía de estilo que coincida con tu organización

Los prompts también reducen la tentación de meter reglas de negocio en nombres de herramientas. Mantén la lógica de negocio en las herramientas y políticas; mantén la guía de flujo en los prompts.

Seguridad y permisos: la parte que no puedes parchear después

Si tu extensión toca sistemas reales, necesita seguridad real. “Es interno” no es una estrategia.

Elige un modelo de auth: delegado por usuario vs delegado por servicio

Dos enfoques comunes:

• User-delegated: la extensión actúa en nombre de un usuario y respeta sus permisos. Lo mejor para herramientas de productividad que deben reflejar el acceso del usuario.
• Service-delegated: la extensión usa una cuenta de servicio con permisos acotados. Lo mejor para automatización controlada y dashboards de solo lectura.

User-delegated suele requerir intercambio de tokens, manejo de sesiones y auditoría cuidadosa. Service-delegated requiere un scoping estricto y puede necesitar herramientas separadas para acciones privilegiadas.

Aplica scopes a las herramientas según el riesgo

No todas las herramientas son iguales. Puedes agruparlas por riesgo y aplicar puertas distintas:

• Read-only: search, list, retrieve
• Write: create, update
• Destructive: delete, purge, revoke
• Financial/legal: billing, contracts, compliance actions

Para herramientas de mayor riesgo, añade requisitos extra:

• Campos de confirmación obligatorios
• Flujo de aprobación de dos personas (donde proceda)
• Modo “dry run”
• Límites de tasa estrictos
• Logs de auditoría detallados

Redacta datos sensibles en ambas direcciones

La redacción no es solo para logs salientes. También afecta a las respuestas.

Si la API downstream devuelve secretos, datos personales o tokens, tu extensión debería:

• Eliminar campos sensibles por defecto
• Proporcionar una representación “mascarada” segura
• Exponer el detalle completo solo con permiso explícito y propósito claro

Registra para auditorías sin filtrar datos

Una política de logging práctica:

• Loggea nombre de la herramienta, timestamp, identidad de usuario, request ID
• Registra hashes o contadores en lugar de contenido bruto
• Almacena payloads crudos solo en sinks de auditoría seguros, si es necesario
• Añade IDs de correlación para llamadas downstream

Esto te da trazabilidad sin convertir tu sistema de logs en una responsabilidad.

Pruebas de extensiones MCP personalizadas como un profesional

La mayoría de los bugs en extensiones no son problemas de sintaxis. Son problemas de integración y casos límite: campos faltantes, respuestas inesperadas downstream, concurrencia y desajustes de permisos.

Tests unitarios: valida esquemas y formas de error

Los unit tests deberían cubrir:

• El esquema rechaza campos desconocidos
• Los campos requeridos son obligatorios
• Restricciones enum
• Normalización de salidas
• Consistencia del sobre de error

Tests de integración: usa sandboxes y fixtures

Para tests de integración:

• Usa sandboxes de proveedores (Jira sandbox, GitHub test org, Stripe test mode)
• Mockea APIs downstream cuando no haya sandboxes
• Graba fixtures para respuestas comunes
• Prueba timeouts y retries

Una buena suite de integración incluye tests de “ensayo de fallos”:

• downstream 500
• downstream 429
• auth expirado
• permiso denegado
• datos parciales devueltos

Tests de contrato: mantén los contratos de herramienta honestos

¿Recuerdas esos contratos de herramienta que escribiste? Conviértelos en tests:

• Un ejemplo de input debe pasar la validación
• Un ejemplo de output debe coincidir con el esquema
• Escenarios de error conocidos deben producir error_codes esperados

Los tests de contrato evitan cambios silenciosos cuando refactorizas.

Documentación que ayuda tanto a humanos como a modelos

En repositorios MCP, la documentación no es decorativa. Es cómo otros desarrolladores y consumidores de herramientas entienden lo que construiste.

Documentación mínima para lanzar:

• Quickstart: cómo ejecutar localmente, vars de entorno necesarias, cómo conectar un cliente
• Tools reference: inputs/outputs, ejemplos, códigos de error
• Security: permisos, scopes, logging de auditoría
• Operational guide: despliegue, monitorización, respuesta a incidentes
• Changelog: cambios visibles para el usuario y migraciones

Escribe ejemplos como si fueran a ser copiados en producción—porque lo serán.

Versionado y compatibilidad hacia atrás: evita rupturas sorpresa

Las extensiones MCP personalizadas evolucionan. La forma más fácil de perder confianza es cambiar salidas sin avisar.

Usa versionado semántico con disciplina

Una política operativa:

• PATCH: correcciones de bugs, sin cambios de esquema
• MINOR: cambios aditivos (nuevos campos opcionales, nuevas herramientas)
• MAJOR: cambios rompientes de esquema, renombrar herramientas, eliminar campos

Marca como obsoleto antes de eliminar

Si necesitas eliminar una herramienta o campo:

• Márcalo como deprecado en la documentación
• Mantenlo funcionando por una ventana definida (30–90 días)
• Añade advertencias en las respuestas si procede
• Proporciona una ruta de migración (“usa la herramienta X con el campo Y en su lugar”)

Esto importa aún más cuando otros repos repos dependen de tu extensión.

Distribución y empaquetado en repositorios MCP

Cómo distribuyes depende de tu entorno:

• Servidor MCP open source publicado en GitHub
• Repo privado en tu organización
• Paquete interno distribuido vía un registry de artefactos
• Imagen de contenedor desplegada en un clúster

Independientemente del método, trata los releases como productos.

Checklist de release

Antes de taggear un release:

• Tests en verde (unit + integration)
• Contratos de herramienta actualizados
• Docs actualizados
• Changelog escrito
• Revisión de seguridad para nuevas herramientas
• Dashboards de monitorización actualizados (si procede)

Si tu extensión se conecta a sistemas críticos, haz un despliegue escalonado.

Observabilidad y operaciones: mantenlo funcionando cuando las cosas se tuercen

El modelo no te dirá que tu extensión es inestable. Los usuarios lo harán—después de que les haga perder tiempo.

Métricas que merece la pena capturar

Al menos sigue:

• Conteo de llamadas por herramienta
• Latencia p50/p95/p99
• Tasa de errores por herramienta y por dependencia downstream
• Conteo de timeouts
• Disparos de límites de tasa
• Fallos de auth

Añade dashboards que te permitan responder: “¿Está rota la extensión o está rota la dependencia downstream?”

Rastrear llamadas downstream

Si tu extensión llama a múltiples servicios, el tracing distribuido te ahorra horas. Incluso IDs de correlación ligeros pueden ayudarte a reconstruir una ruta de fallo.

Degradación segura

Cuando una dependencia está caída, no lances errores crípticos. Proporciona:

• Un mensaje claro
• Si reintentar podría funcionar
• Una alternativa sugerida (modo solo lectura, datos en caché)
• Enlace a una página de estado si tienes una

Esto hace que la extensión parezca fiable incluso bajo estrés.

Un control de calidad a mitad de proyecto: la auditoría de “calidad de la extensión”

A mitad de construcción, pausa y ejecuta una auditoría con estas preguntas:

• ¿Se puede describir cada herramienta en una frase?
• ¿Son los nombres de herramientas consistentes y previsibles?
• ¿Son los esquemas estrictos y validados?
• ¿Están las salidas normalizadas y estables?
• ¿Existen códigos de error y mapean a acciones?
• ¿Se hacen cumplir permisos en el servidor?
• ¿Se redactan datos sensibles?
• ¿Tenemos al menos un test de integración por herramienta?
• ¿Un desarrollador nuevo entendería cómo añadir una herramienta en una hora?

Si respondes “no” a varias, arregla la estructura ahora. Solo se hace más difícil después.

Construir extensiones de ejemplo: tres planos prácticos

Una guía se vuelve real cuando puedes imaginar lo que estás construyendo. Aquí tienes tres planos que se ajustan bien a casos de uso comunes en repositorios MCP. Cada uno puede implementarse como un servidor pequeño con un puñado de herramientas y recursos.

1. Internal Docs Navigator

   • Tools: search_docs, get_doc_section, list_collections
   • Resources: docs/{doc_id}, docs/{doc_id}/sections/{section_id}
   • Prompts: “Answer with citations from docs”
   • Key concerns: access control, content chunking, citations, freshness

2. Ticketing and Incident Assistant

   • Tools: create_ticket, update_ticket, link_ticket, summarize_ticket, assign_oncall
   • Resources: tickets/{key}, incidents/{id}
   • Prompts: “Triage and propose next steps”
   • Key concerns: idempotency for creation, role-based permissions, audit logs

3. **Data Warehouse Read-Only Query Server **

   • Tools: run_query_readonly, explain_query, list_tables, describe_table
   • Resources: schemas/{name}, tables/{name}
   • Prompts: “Write safe SQL and summarize results”
   • Key concerns: strict read-only enforcement, query timeouts, result limits, PII masking

Estos planos no están pensados para copiarse línea por línea. Están pensados para mostrar cómo es “pequeño pero completo” en repositorios MCP.

Manejo de idempotencia, concurrencia y “llamadas dobles”

Los sistemas que invocan herramientas pueden disparar llamadas repetidas para la misma intención—a veces por reintentos, a veces por que el usuario vuelve a pedirlo, otras por reconexiones del cliente.

Añade claves de idempotencia para operaciones de escritura

Para herramientas que crean o mutan datos, acepta un idempotency_key opcional:

• Si se usa la misma clave otra vez, devuelve el resultado original.
• Almacena registros de idempotencia por un TTL razonable.
• Documenta cuánto tiempo permanecen válidas las claves.

Esto evita tickets duplicados, facturas duplicadas, invitaciones de usuario duplicadas—fallos clásicos de extensiones.

Protégete contra fallos parciales

Si tu herramienta realiza varios pasos:

• Prefiere transacciones si el downstream las soporta.
• De lo contrario, diseña pasos de compensación (rollback) o un flujo de “resume”.
• Devuelve IDs intermedios para que los humanos puedan investigar.

La meta no es ser perfecto; es ser recuperable.

Hacer las extensiones “amigables para modelos” sin depender de un modelo

Es tentador adaptar todo a los hábitos de un modelo concreto. Resiste. Construye extensiones que sean agnósticas al cliente y agnósticas al modelo.

Mantén nombres de herramientas y campos literales

Evita nombres ingeniosos y campos sobrecargados. Usa términos que tu empresa ya emplea:

• customer_id en lugar de cid
• invoice_number en lugar de inv
• priority con un enum conocido

La nomenclatura literal mejora la precisión y hace tus docs buscables.

Pon las reglas de negocio en el servidor, no en el prompt

Los prompts ayudan a que los modelos sigan reglas, pero la aplicación corresponde al código:

• comprobaciones de permisos
• aprobaciones requeridas
• transiciones permitidas
• restricciones de política (p. ej., “nunca consultar estas tablas”)

Si una regla importa, aplícala. Los prompts son orientación, no seguridad.

Un flujo práctico para añadir una nueva herramienta

Cuando un stakeholder pregunta “¿Podemos añadir una herramienta que haga X?”, sigue un flujo repetible.

1. Aclarar el trabajo
   ¿Cuál es la meta real del usuario? ¿Qué sistema es la fuente de la verdad?

2. Redactar el contrato de herramienta
   Inputs/outputs, errores, scope de permisos.

3. Revisar por seguridad
   ¿Puede borrar datos? ¿Puede exponer PII? ¿Podría ser abusada?

4. Implementar con validación
   Esquema estricto, salidas normalizadas, sobre de error.

5. Añadir tests
   Unit tests para esquema y errores; integration tests para la llamada downstream.

6. Documentar y lanzar
   Actualizar docs de tools, ejemplos y changelog. Taggear release.

Este flujo es aburrido—en el mejor sentido. Reduce el “conocimiento tribal” y hace que el desarrollo de extensiones escale.

Errores comunes en extensiones MCP personalizadas (y cómo evitarlos)

Error: Exponer una herramienta “run_any_command”

Una herramienta que ejecuta comandos o consultas arbitrarias es una invitación al desastre. Incluso SQL arbitrario de solo lectura puede filtrar datos sensibles si fallas en controlar una tabla o vista.

Arreglo:

• Proporciona consultas acotadas o herramientas de informe preconstruidas
• Aplica allowlists
• Añade límites de filas y enmascarado de columnas

Error: Devolver texto no acotado

Devolver blobs masivos perjudica el rendimiento y aumenta la probabilidad de que el modelo pierda detalles clave.

Arreglo:

• Devuelve resúmenes más una forma de obtener más
• Paginación
• Chunking intencionado de recursos

Error: Mensajes de error débiles

“Algo salió mal” no es aceptable cuando un modelo está orquestando llamadas.

Arreglo:

• Estandariza códigos de error
• Incluye sugerencias de arreglo
• Marca claramente los errores reintentables

Error: Sin plan operativo

Si nadie posee monitorización y on-call, la extensión se degradará en silencio.

Arreglo:

• Añade dashboards básicos
• Define ownership
• Documenta pasos de incidente

Publicar y mantener tu extensión a lo largo del tiempo

Una extensión MCP no está “terminada” cuando funciona una vez. La fase de mantenimiento es donde se construye la confianza.

Trata los cambios en APIs downstream como un riesgo de primera clase

Si te integras con vendors SaaS:

• Sigue sus changelogs
• Fija versiones de API cuando sea posible
• Añade tests de integración que se ejecuten regularmente
• Incluye notas de compatibilidad en tus docs

Mantén un bucle de feedback estrecho con los usuarios

Observa cómo la gente usa realmente la extensión:

• ¿Qué herramientas se usan más?
• ¿Qué herramientas fallan más?
• ¿Qué piden los usuarios repetidamente que podría convertirse en una plantilla de prompt?
• ¿Dónde fuerza la gente pasos manuales?

A menudo la mejor “nueva característica” no es una herramienta nueva: son mejores valores por defecto, salidas más claras o un flujo de trabajo más seguro.

Establece directrices de contribución en tu repo MCP

Si varios equipos van a añadir herramientas, necesitas estándares:

• Convenciones de nombres
• Estilo de esquemas
• Formato del sobre de error
• Requisitos de logging y redacción
• Requisitos de tests
• Checklist de revisión para seguridad

Un CONTRIBUTING.md corto y una plantilla de PR pueden evitar semanas de limpieza luego.

Cerrar el círculo: tu extensión debe inspirar confianza

Una gran extensión MCP se siente como un compañero de trabajo fiable: claro sobre lo que puede hacer, honesto sobre lo que no puede, y consistente bajo presión. Construye pequeño, valida todo, registra responsablemente, documenta sin piedad y versiona como si otros fuesen a depender de ello—porque lo harán.

External Links

MCP developer guide | Visual Studio Code Extension API Build an MCP App - Model Context Protocol Build your MCP server – Apps SDK | OpenAI Developers Making your own MCP server in VS Code | Microsoft Learn Visual Studio Code + Model Context Protocol (MCP) Servers Getting …

External References

• Internal Docs Navigator
• and Incident Assistant
• Read Only Query Server