Servidor MCP

Archyl proporciona un servidor Model Context Protocol (MCP) que permite que los asistentes de IA interactúen con tu documentación de arquitectura. Esto habilita una exploración y documentación de arquitectura potentes impulsadas por IA.

¿Qué es MCP?

El Model Context Protocol (MCP) es un protocolo abierto que permite que los asistentes de IA accedan de forma segura a herramientas y fuentes de datos externos. Con el servidor MCP de Archyl, tu asistente de IA puede:

• Listar y navegar tus proyectos
• Crear y modificar elementos de arquitectura
• Generar documentación
• Responder preguntas sobre tu arquitectura

Herramientas Soportadas

El servidor MCP de Archyl funciona con:

• Antigravity - El IDE impulsado por IA de Google
• Claude Code - La herramienta CLI de Anthropic
• Claude Desktop - La aplicación de escritorio de Claude
• Cursor - Editor de código orientado a IA
• OpenAI Codex - El asistente de codificación IA de OpenAI
• VS Code - Con GitHub Copilot Chat
• Warp - Terminal moderno con integración de IA
• Windsurf - El IDE impulsado por IA de Codeium

Autenticación

El servidor MCP requiere una clave API para autenticación. Dependiendo de la herramienta que uses:

• Herramientas con soporte de headers (Claude Code, Cursor, Warp, Windsurf, Antigravity): Usa el header X-API-Key
• Herramientas sin soporte de headers (Claude Desktop, VS Code, OpenAI Codex): Usa el parámetro ?apiKey=TU_CLAVE_API en la URL

Genera una clave API desde tu página Perfil → Claves API.

Configuración

Antigravity

1. Abre Antigravity y haz clic en el menú "..." en el panel Agent
2. Selecciona "MCP Servers" > "Manage MCP Servers" > "View raw config"
3. Añade a ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "TU_CLAVE_API"
      }
    }
  }
}

4. Reinicia Antigravity para aplicar los cambios

Nota: Antigravity usa serverUrl en lugar de url para servidores MCP basados en HTTP.

Claude Code

Crea un archivo .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "archyl": {
      "type": "http",
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "TU_CLAVE_API"
      }
    }
  }
}

Ejecuta Claude Code - detectará automáticamente el servidor MCP.

Claude Desktop

1. Abre la configuración de Claude Desktop
2. Navega a Desarrollador → Servidores MCP
3. Haz clic en "Agregar Servidor" y añade:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp?apiKey=TU_CLAVE_API"
    }
  }
}

4. Reinicia Claude Desktop

Nota: Los conectores remotos de Claude Desktop no soportan headers personalizados, por lo que la clave API debe pasarse como parámetro de URL.

Cursor

Crea un archivo .cursor/mcp.json en tu proyecto:

{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "TU_CLAVE_API"
      }
    }
  }
}

Reinicia Cursor para cargar el servidor MCP.

OpenAI Codex

Abre o crea ~/.codex/config.toml y añade:

[mcp_servers.archyl]
url = "https://api.archyl.com/mcp?apiKey=TU_CLAVE_API"

Reinicia Codex CLI o IDE para aplicar los cambios.

VS Code

1. Abre la configuración de VS Code (Cmd/Ctrl + ,)
2. Busca "MCP" y haz clic en "Editar en settings.json"
3. Añade:

{
  "mcp": {
    "servers": {
      "archyl": {
        "url": "https://api.archyl.com/mcp?apiKey=TU_CLAVE_API"
      }
    }
  }
}

Warp

1. Abre Warp y ve a Configuración > Servidores MCP
2. Haz clic en "Añadir servidor" y pega la configuración:

{
  "archyl": {
    "url": "https://api.archyl.com/mcp",
    "headers": {
      "X-API-Key": "TU_CLAVE_API"
    }
  }
}

3. Reinicia Warp para aplicar los cambios

Windsurf

Abre el archivo de configuración MCP en ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "TU_CLAVE_API"
      }
    }
  }
}

Reinicia Windsurf para aplicar los cambios.

Herramientas Disponibles

Una vez conectado, tu asistente de IA puede usar estas herramientas:

Gestión de Proyectos

Elementos de Arquitectura

Relaciones

Documentación

Conversaciones de Ejemplo

Explorando Arquitectura

Tú: "¿Qué sistemas hay en mi proyecto de e-commerce?"

IA: Usa la herramienta list_systems "Tu proyecto de e-commerce tiene 4 sistemas: Tienda Web, Servicio de Pagos, Sistema de Inventario y Servicio de Notificaciones..."

Creando Elementos

Tú: "Agrega un nuevo contenedor llamado Redis Cache al sistema Tienda Web para almacenamiento de sesiones"

IA: Usa la herramienta create_container "He creado el contenedor Redis Cache en el sistema Tienda Web con la descripción 'Caché en memoria para almacenamiento de sesiones'."

Documentación

Tú: "Crea un ADR para nuestra decisión de usar PostgreSQL en lugar de MongoDB"

IA: Usa la herramienta create_adr "He creado ADR-001: Selección de Tecnología de Base de Datos, documentando la decisión de usar PostgreSQL por su cumplimiento ACID y flexibilidad de consultas..."

Endpoint

HTTP Streamable (MCP)

https://api.archyl.com/mcp

Usa este endpoint para conectar tu asistente de IA a la documentación de arquitectura de Archyl. Soporta el protocolo de transporte HTTP Streamable.

Solución de Problemas

Conexión Fallida

• Verifica que tu clave API sea válida
• Asegúrate de que la URL del endpoint sea correcta
• Verifica tu conexión de red

Autenticación Fallida

• Para herramientas con soporte de headers: Verifica que el header X-API-Key esté configurado correctamente
• Para herramientas sin soporte de headers: Verifica que el parámetro ?apiKey= esté en la URL
• Asegúrate de que tu clave API no haya expirado

Herramienta No Encontrada

• Asegúrate de estar usando el nombre correcto de herramienta
• Verifica que tu clave API tenga los permisos requeridos

Problemas específicos de Antigravity

• Asegúrate de usar serverUrl (no url) para la configuración
• La ubicación del archivo de config es ~/.gemini/antigravity/mcp_config.json

Problemas específicos de OpenAI Codex

• Asegúrate de que la sintaxis TOML sea correcta en ~/.codex/config.toml
• Usa [mcp_servers.archyl] como nombre de tabla

Problemas específicos de Warp

• Navega a Configuración > Servidores MCP para gestionar configuraciones
• Reinicia Warp después de realizar cambios en la configuración

Mejores Prácticas

Sé Específico

Cuando pidas a tu IA que modifique arquitectura, sé específico:

• Incluye nombres de proyectos
• Especifica tipos de elementos
• Proporciona descripciones

Revisa los Cambios

Siempre revisa los elementos creados por IA:

• Verifica que nombres y descripciones sean precisos
• Verifica que las relaciones sean correctas
• Actualiza según sea necesario

Usa para Exploración

MCP es excelente para:

• Explorar rápidamente arquitecturas grandes
• Generar documentación inicial
• Responder preguntas sobre tus sistemas