Conectores YAML

El motor YAML es la vía de autoría sin código. Compila un manifiesto declarativo en la misma superficie MCP que un servidor tipado: herramientas con parámetros, Presenters mediante transformaciones de respuesta, recursos, prompts y conexiones. Úsalo para envolver rápidamente una API REST interna; pasa a código MVA tipado cuando el dominio necesite comportamiento personalizado.

Un manifiesto completo

version: "1.0"
server:
  name: billing
  description: Invoice operations for an AI agent
  capabilities:
    tools: true
    resources: true
secrets:
  BILLING_TOKEN:
    label: Billing API token
    type: api_key
    required: true
    sensitive: true
connections:
  billing:
    type: rest
    base_url: https://api.example.com
    auth:
      type: bearer
      token: ${SECRETS.BILLING_TOKEN}
tools:
  - name: list_invoices
    description: List invoices for the current account
    rules:
      - Never expose internal_notes to the model
    parameters:
      account_id:
        type: string
        required: true
        description: Account identifier
    execute:
      connection: billing
      method: GET
      path: /accounts/{{account_id}}/invoices
    response:
      extract: [data]
      max_items: 50

El parser valida el esquema raíz con Zod, comprueba referencias cruzadas, interpola ${SECRETS.KEY} desde el entorno, compila parámetros a JSON Schema, resuelve la conexión y construye un servidor MCP local.

La superficie del manifiesto

• server: nombre, descripción, capabilities e instrucciones
• secrets: declaraciones tipadas como api_key, token, password, url, y flags required y sensitive
• connections: URL base REST, autenticación (none, bearer, basic o custom header), headers, timeout y política de retry
• tools: descripción, instrucción, reglas, tags, anotaciones, parámetros, bloque HTTP execute y transformación de respuesta
• resources: plantillas de URI, contenido estático o obtenido, tipo MIME y caché opcional
• prompts: argumentos primitivos planos y plantillas de mensajes de usuario/asistente con {{argument}}
• settings: declaraciones de exposition, DLP, FinOps, circuit breaker y ciclo de vida

La CLI

mcpfusion yaml validate mcpfusion.yaml
mcpfusion yaml dev mcpfusion.yaml --transport http --port 3001

La CLI detecta automáticamente mcpfusion.yaml o mcpfusion.yml en el directorio actual. validate se detiene después de comprobar el esquema y las referencias cruzadas. dev ejecuta stdio de forma predeterminada o Streamable HTTP en el puerto seleccionado.

El paquete YAML actual incluye los comandos validate y dev en la CLI OSS. Despliega el conector compilado mediante el flujo habitual de Deploy; no supongas que existe un comando separado de despliegue YAML a menos que lo exponga tu CLI instalada.

Lo que impone OSS

El motor abierto impone la forma del esquema, los campos obligatorios, los tipos de parámetros, las referencias cruzadas, la interpolación de secretos y la ejecución REST. Las claves de settings para DLP, FinOps, circuit breaker y ciclo de vida se procesan como parte del manifiesto; la aplicación de esos controles de plataforma corresponde a Vinkius Cloud. Esta separación permite ejecutar el mismo YAML localmente mientras el conector alojado obtiene el perímetro de la plataforma.

Cuando YAML deja de ser suficiente

Elige código MVA tipado cuando necesites Presenters dinámicos, esquemas dependientes del rol, middleware personalizado, transacciones, puertas de estado FSM, handlers de generadores o recuperación de errores específica del dominio. La migración no reescribe el protocolo: las mismas herramientas, recursos y prompts pueden reconstruirse con initMCPFusion() y desplegarse con el mismo comando.

Próximos pasos

• The MVA pattern: la ruta tipada hacia la que compila YAML
• Credentials: declara secretos gestionados por el comprador
• CLI: los comandos compartidos de desarrollo