---
title: Flujos de trabajo de integración
description: Patrones prácticos para integrar Verdent con herramientas y servicios externos
---



### Lo que aprenderás

Flujos de trabajo prácticos de integración que combinan subagentes personalizados, reglas y servidores MCP para escenarios de desarrollo reales.

---

## Métodos de integración

| Método | Ideal para | Configuración |
|--------|----------|---------------|
| **Subagentes personalizados** | Tareas especializadas impulsadas por IA | `~/.verdent/subagents/*.md` |
| **Reglas (AGENTS.md)** | Estándares y comportamiento del equipo | `AGENTS.md` en la raíz del proyecto |
| **Servidores MCP** | Herramientas externas compatibles con el protocolo | `.mcp.json` (raíz del proyecto) |

**Filosofía:** Combina métodos para crear flujos de trabajo completos adaptados a tus necesidades.

---

## Patrones comunes de integración

### Flujo de trabajo de desarrollo de bases de datos

**Stack:** Subagente revisor de migraciones + estándares de AGENTS.md + servidor MCP de PostgreSQL

**Subagente:**
```markdown
---
name: migration-reviewer
description: Reviews database migrations for safety
---
Checks: Destructive operations, reversibility, indexing, blocking operations
```

**AGENTS.md:**
```markdown
## Database Standards
- All migrations reviewed by @migration-reviewer
- Test on staging before production
- Include rollback procedures
```

**MCP:** Servidor PostgreSQL para ejecución de consultas, inspección de esquemas y validación de migraciones

**Flujo de trabajo:** Escribir la migración → @migration-reviewer la valida → MCP la prueba en staging → documentación del PR

---

### Desarrollo de API con seguridad

**Stack:** Auditor de seguridad + reglas de AGENTS.md + herramienta de pruebas personalizada de API

**Componentes:**
- **Subagente:** `@api-security-auditor` - Validación de entradas, inyección SQL, autenticación, limitación de tasa
- **Reglas:** Todos los endpoints requieren revisión de seguridad, limitación de tasa en los API públicos
- **Herramientas externas:** Pruebas automatizadas de endpoints y análisis de seguridad mediante integración personalizada

**Resultado:** Revisión de seguridad automática antes de aprobar el PR.

<Note>
Las herramientas de pruebas de API y de análisis de seguridad pueden integrarse mediante implementaciones personalizadas de servidores MCP u otros métodos de integración, según tus herramientas.
</Note>

---

### Accesibilidad del frontend

**Stack:** Auditor de accesibilidad + reglas WCAG + integración de Lighthouse

**Flujo de trabajo:**
```
Create component → @a11y-auditor reviews → Lighthouse tests accessibility → Rules enforce >90 score
```

<Note>
Lighthouse y otras herramientas de accesibilidad pueden integrarse a través de servidores MCP personalizados o mediante la integración con tu pipeline de CI/CD, según tu flujo de trabajo.
</Note>

---

## Ejemplos de configuración de MCP

### Entender MCP

**Model Context Protocol (MCP)** es un protocolo abierto que estandariza la forma en que las aplicaciones proporcionan contexto a los LLM. Los servidores MCP son ejecutables que implementan el protocolo. No son conexiones de bases de datos ni endpoints de API, sino programas que se ejecutan y se comunican mediante JSON-RPC 2.0.

**Conceptos clave:**
- **Servidores MCP**: Ejecutables (paquetes de Node.js, scripts de Python, etc.) que implementan el protocolo MCP
- **Configuración**: Le indica a Verdent cómo iniciar el servidor (`command` + `args`)
- **Comunicación**: Los servidores gestionan su propia lógica de negocio (consultas, llamadas a API, etc.)

### Configuración básica

**Ubicación:** `.mcp.json` en la raíz del proyecto

<CodeGroup>
```json PostgreSQL Server
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    }
  }
}
```

```json GitHub Server
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```

```json Multiple Servers
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/myapp_dev"
      ]
    },
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}
```
</CodeGroup>

**Explicación:**
- `mcpServers` - Clave de nivel superior requerida para la configuración de MCP
- `command` - Ejecutable que se va a ejecutar (normalmente `npx` para paquetes de Node.js)
- `args` - Argumentos que se pasan al comando (nombre del paquete, cadenas de conexión, etc.)
- `env` - Variables de entorno para autenticación/configuración

### Múltiples entornos

```json
{
  "mcpServers": {
    "postgres-dev": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${DEV_DATABASE_URL}"
      ]
    },
    "postgres-staging": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${STAGING_DATABASE_URL}"
      ]
    },
    "postgres-prod": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "${PROD_DATABASE_URL}"
      ]
    }
  }
}
```

**Práctica recomendada:** Usa variables de entorno para las cadenas de conexión y mantener las credenciales seguras. Los servidores MCP gestionan internamente el comportamiento de solo lectura según su implementación. Consulta la documentación del servidor específico para conocer las opciones de control de acceso.

<Tip>
**Más información sobre MCP:**
- [Especificación de Model Context Protocol](https://modelcontextprotocol.io/specification)
- [Registro de servidores MCP](https://mcp.so/servers) - Explora los servidores MCP disponibles
- [Servidores MCP oficiales](https://github.com/modelcontextprotocol) - PostgreSQL, GitHub, Filesystem y más
</Tip>

---

## Integración con el espacio de trabajo

### Configuración específica del proyecto

**Configuración:**
1. Almacénalo en la raíz del proyecto: `.mcp.json`
2. Confírmalo en el control de versiones para compartirlo con el equipo
3. Los miembros del equipo usan automáticamente los servidores MCP del proyecto

**Ejemplo de microservicios:**
```json
{
  "mcpServers": {
    "users-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5432/users"
      ]
    },
    "orders-db": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://localhost:5433/orders"
      ]
    }
  }
}
```

<Note>
Para servicios adicionales como Kafka, necesitarías una implementación de servidor MCP compatible. El registro oficial de servidores MCP en [mcp.so/servers](https://mcp.so/servers) lista los servidores comunitarios disponibles.
</Note>

---

## Colaboración en equipo

### Estándares compartidos de AGENTS.md

Confírmalos en el control de versiones para mantener la consistencia en todo el equipo:

```markdown
# AGENTS.md

## Code Review Process
- Run @code-reviewer before PR
- Address all security warnings
- Minimum 80% test coverage

## Integration Requirements
- @migration-reviewer for database changes
- @api-security-auditor for new endpoints
- @a11y-auditor for UI components

## MCP Servers
- Use postgres-staging MCP server for queries
- Never use postgres-prod MCP server for exploratory queries
```

**Beneficios:** Comportamiento consistente, estándares aplicados y controles de calidad automáticos.

---

## Coordinación de múltiples agentes

### Flujo de trabajo de funciones complejas

**Ejemplo:** Nuevo endpoint de pagos

```
1. Developer request → 2. Main agent generates code →
3. @api-security-auditor reviews security →
4. @migration-reviewer validates schema →
5. MCP tests on staging →
6. Main agent generates tests and PR
```

**Resultado:** Endpoint completamente revisado con las prácticas recomendadas de seguridad y bases de datos aplicadas.

---

## Prácticas recomendadas de integración

### Adopción progresiva

**Fase 1:** Reglas básicas
```markdown
## Code Standards
- Use TypeScript strict mode
- Run tests before commit
```

**Fase 2:** Agregar un subagente especializado
```markdown
## Code Review
- Run @security-reviewer before PR
```

**Fase 3:** Integrar MCP
```markdown
## Database Access
- Use MCP postgres-staging for queries
```

### Combinaciones estratégicas

| Combinación | Propósito | Ejemplo |
|-------------|---------|---------|
| Reglas + subagentes | Las reglas definen *cuándo*, los subagentes *analizan* | AGENTS.md: "Revisar con @security-reviewer" |
| Reglas + MCP | Las reglas especifican *qué* servidores, MCP *accede* | AGENTS.md: "Usar solo db-staging" |
| Subagentes + MCP | El subagente usa MCP para *datos externos* | El auditor de seguridad consulta los endpoints de API |

### Prácticas recomendadas de documentación para el equipo

Cuando documentes las integraciones para tu equipo, incluye:

- **Subagentes personalizados**: Lista el nombre, propósito y momento de invocación de cada subagente
- **Reglas de AGENTS.md**: Documenta las reglas con una justificación que explique el "por qué" de cada estándar
- **Servidores MCP**: Describe el propósito de cada servidor, su nivel de acceso (solo lectura/escritura) y cuándo usarlo
- **Flujos de trabajo de integración**: Proporciona flujos de trabajo de ejemplo que muestren cómo los componentes funcionan en conjunto
- **Resolución de problemas**: Documenta los problemas comunes específicos de tu configuración y sus soluciones

<Tip>
Confirma la documentación de integración junto con tus archivos `.mcp.json` y `AGENTS.md` para que los nuevos miembros del equipo entiendan rápidamente tu configuración.
</Tip>

---

## Resolución de problemas

<Tabs>
  <Tab title="Problemas de subagentes">
    **Problema:** El subagente no se invoca cuando se espera

    **Verifica:**

    **Ubicación**: El archivo existe en `~/.verdent/subagents/[name].md`

    **Frontmatter YAML**: Sintaxis válida con los campos requeridos `name` y `description`

    **Política de invocación**: Coincide con el uso (el modo estricto requiere una mención explícita con @)

    **Descripción**: El campo `description` del agente describe con precisión cuándo debe usarse el subagente

    **Reinicio**: Prueba a reiniciar Verdent para recargar las definiciones de subagentes

    ---

    **Causas comunes:**
    - Error tipográfico en el nombre del archivo del subagente o en la mención con @
    - Sintaxis YAML inválida en el frontmatter
    - El `description` del subagente no coincide con el contexto de la tarea
  </Tab>

  <Tab title="Problemas de AGENTS.md">
    **Problema:** Las reglas de AGENTS.md no se aplican

    **Verifica:**

    **Ubicación**: El archivo está en el directorio raíz del proyecto

    **Sintaxis**: Markdown válido sin errores de análisis

    **Estilo de directivas**: Usa comandos específicos ("Siempre usa..." en lugar de "Intenta...")

    **Sesión**: Inicia una nueva conversación para probar la aplicación de reglas desde cero

    **Conflictos**: Verifica si las reglas del usuario anulan involuntariamente las reglas del proyecto

    ---

    **Causas comunes:**
    - AGENTS.md en el directorio equivocado (debe estar en la raíz del proyecto)
    - Instrucciones vagas que la IA interpreta de forma diferente
    - Reglas aplicadas pero con resultados inesperados (ajusta la redacción)
  </Tab>

  <Tab title="Problemas del servidor MCP">
    **Problema:** El servidor MCP no se inicia o no se conecta

    **Verifica:**

    **Sintaxis**: `.mcp.json` contiene JSON válido (usa `jq` para validar)

    **Estructura**: La clave requerida `mcpServers` está presente en el nivel superior

    **Configuración del servidor**: Cada servidor tiene `command` y `args` especificados correctamente

    **Paquete**: El paquete del servidor MCP es accesible (`npx` descarga los paquetes automáticamente; la opción `-y` omite el mensaje de confirmación)

    **Entorno**: Las variables del objeto `env` están configuradas correctamente en tu shell

    **Permisos**: El ejecutable del servidor tiene los permisos de ejecución adecuados

    ---

    **Causas comunes:**
    - Error tipográfico en el JSON (coma faltante, corchete sin cerrar)
    - Nombre de paquete incorrecto en el array args
    - Variables de entorno faltantes o incorrectas
    - Red/firewall que bloquea la instalación del paquete npx

    ---

    **Pasos de depuración:**
    1. Valida el JSON: `cat .mcp.json | jq .`
    2. Prueba el comando manualmente: `npx -y @modelcontextprotocol/server-postgres "postgresql://..."`
    3. Verifica el entorno: `echo $GITHUB_TOKEN`
    4. Revisa los registros de Verdent para ver mensajes de error específicos
  </Tab>
</Tabs>

---

## Véase también

<CardGroup cols={2}>
  <Card title="Guía de extensibilidad" icon="puzzle-piece" href="/docs/verdent-for-vscode/advanced-features/extensibility">
    Resumen completo de los métodos de extensión
  </Card>
  <Card title="Integración de MCP" icon="plug" href="/docs/verdent-for-vscode/advanced-features/mcp">
    Detalles de Model Context Protocol
  </Card>
</CardGroup>