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:

• Navegar y consultar tus proyectos y todo su modelo C4
• Crear y modificar elementos de arquitectura, relaciones y diagramas
• Leer y escribir ADRs, documentación, contratos de API y canales de eventos
• Comprobar reglas de conformidad, puntuaciones de deriva, métricas DORA y propiedad antes de escribir código
• Hacer seguimiento de releases, solicitudes de cambio, comentarios e historial

Clientes compatibles

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

Clave API (recomendado)

La mayoría de los clientes se autentican con una clave API. 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.

Los permisos de la clave deciden lo que puede hacer el asistente: una clave de solo lectura puede llamar a todas las herramientas list_* y get_*, mientras que create_*, update_*, delete_* e import_dsl requieren una clave con permiso de escritura. Darle a tu agente una clave de solo lectura es la forma más sencilla de dejar que explore tu arquitectura sin que pueda modificarla.

OAuth 2.1

El servidor también implementa OAuth 2.1 con registro dinámico de clientes, para clientes que se conectan mediante un inicio de sesión en el navegador en lugar de una clave pegada (los permisos mcp:read y mcp:write reflejan los permisos de clave API descritos arriba). Apunta ese cliente al mismo endpoint y descubrirá el flujo automáticamente a través de:

https://api.archyl.com/.well-known/oauth-authorization-server
https://api.archyl.com/.well-known/oauth-protected-resource

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.

Referencia de herramientas

El servidor expone 189 herramientas. Siguen un esquema de nombres predecible, así que un asistente casi siempre puede adivinar la correcta:

La mayoría de las herramientas con ámbito de proyecto reciben un projectId; las herramientas con ámbito de elemento reciben un elementId más un elementType (el nivel C4: 1 = sistema, 2 = contenedor, 3 = componente, 4 = código). Pide a tu asistente que llame primero a list_projects — de ahí obtendrá los IDs que necesite.

Tu cliente descubre esta lista automáticamente vía tools/list, así que siempre está sincronizada con el servidor. Las tablas siguientes son para que las personas decidan qué pedir.

Perfiles de herramientas

189 herramientas es más de lo que necesita un agente de código para una tarea acotada — anunciarlas todas cuesta contexto. Añade ?profile=coding a la URL del MCP (o envía la cabecera X-Archyl-Tool-Profile: coding) para reducir la superficie a 16 herramientas: contexto por tarea, el ciclo de sesiones de trabajo del harness y las comprobaciones de conformidad/diff. Omite el parámetro (o usa profile=full) para el catálogo completo.

Contexto de agente (4)

Empieza por aquí: estas dan al asistente el panorama de la arquitectura en una sola llamada, en lugar de muchas.

Sesiones de trabajo del Harness (8)

El ciclo de trabajo gobernado para agentes de código: declara una unidad de trabajo para obtener contexto enfocado y bloqueos consultivos, envía latidos mientras trabajas y termina con un resultado que puede abrir una solicitud de cambio de arquitectura. Además, memoria de proyecto: recuerda hechos para futuros trabajadores y recupera lo que aprendieron las sesiones anteriores.

Proyectos (7)

Organizaciones y equipos (5)

Elementos C4 (15)

Sistemas (nivel 1), contenedores (nivel 2), componentes (nivel 3) y elementos de código (nivel 4).

Relaciones (4)

Disposición de diagramas y overlays (5)

Documentación (11)

Architecture Decision Records (6)

Contratos de API (8)

Contratos OpenAPI, gRPC, GraphQL, AsyncAPI y de herramientas MCP.

Canales de eventos (8)

Flujos y pizarras (8)

Comentarios y discusiones (11)

Propiedad (6)

Tecnologías y radar (10)

Releases y entornos (10)

Solicitudes de cambio de arquitectura (6)

Reglas de conformidad (9)

Detección de deriva (4)

Métricas DORA, ROI y predicciones (4)

Historial y viaje en el tiempo (5)

Insights (3)

Marketplace y widgets (15)

Webhooks (7)

Arquitectura de toda la organización (9)

Vistas entre proyectos y artefactos a nivel de organización.

Arquitectura como código (1)

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..."

Antes de escribir código

Tú: "Estoy a punto de añadir limitación de tasa al flujo de checkout. ¿Qué debería saber?"

IA: Usa find_relevant_context e impact_of "El checkout toca el API Gateway y el servicio Orders. Cambiar el gateway afecta a 6 contenedores dependientes. El ADR-014 ya exige Redis para el throttling, y una regla de conformidad prohíbe nuevas dependencias del almacén Session heredado..."

Comprobación de gobernanza

Tú: "¿Nos estamos desviando de la arquitectura documentada?"

IA: Usa get_drift_score y run_conformance_check "La puntuación de deriva es del 82% (bajó desde el 91% del mes pasado). Dos infracciones: el servicio Search llama directamente a la base de datos de Orders, y Payments usa un cliente HTTP no aprobado..."

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 la herramienta — consulta la referencia de herramientas, o pide a tu cliente que actualice su lista de herramientas
• Algunos clientes cachean tools/list; reinicia el cliente después de actualizar

Herramientas de Escritura Rechazadas

• create_*, update_*, delete_* e import_dsl necesitan una clave API con permiso de escritura — una clave de solo lectura solo puede llamar a list_* y get_*
• Revisa tu plan de suscripción: algunas funcionalidades (webhooks, conexiones del marketplace, ejecuciones de agentes gestionadas) dependen del plan

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