Serveur MCP - Archyl Docs

Connectez les assistants IA comme Claude, Cursor et VS Code à votre documentation d'architecture

Serveur MCP

Archyl fournit un serveur Model Context Protocol (MCP) qui permet aux assistants IA d'interagir avec votre documentation d'architecture. Cela permet une exploration et une documentation de l'architecture puissantes propulsées par l'IA.

Qu'est-ce que MCP ?

Le Model Context Protocol (MCP) est un protocole ouvert qui permet aux assistants IA d'accéder de manière sécurisée à des outils et sources de données externes. Avec le serveur MCP d'Archyl, votre assistant IA peut :

  • Lister et parcourir vos projets
  • Créer et modifier des éléments d'architecture
  • Générer de la documentation
  • Répondre aux questions sur votre architecture

Outils Supportés

Le serveur MCP d'Archyl fonctionne avec :

  • Antigravity - L'IDE propulsé par l'IA de Google
  • Claude Code - L'outil CLI d'Anthropic
  • Claude Desktop - L'application de bureau de Claude
  • Cursor - Éditeur de code orienté IA
  • OpenAI Codex - L'assistant de codage IA d'OpenAI
  • VS Code - Avec GitHub Copilot Chat
  • Warp - Terminal moderne avec intégration IA
  • Windsurf - L'IDE propulsé par l'IA de Codeium

Authentification

Le serveur MCP nécessite une clé API pour l'authentification. Selon l'outil que vous utilisez :

  • Outils avec support des headers (Claude Code, Cursor, Warp, Windsurf, Antigravity) : Utilisez le header X-API-Key
  • Outils sans support des headers (Claude Desktop, VS Code, OpenAI Codex) : Utilisez le paramètre ?apiKey=VOTRE_CLE_API dans l'URL

Générez une clé API depuis votre page Profil → Clés API.

Configuration

Antigravity

  1. Ouvrez Antigravity et cliquez sur le menu "..." dans le panneau Agent
  2. Sélectionnez "MCP Servers" > "Manage MCP Servers" > "View raw config"
  3. Ajoutez à ~/.gemini/antigravity/mcp_config.json :
{
  "mcpServers": {
    "archyl": {
      "serverUrl": "https://api.archyl.com/mcp",
      "headers": {
        "X-API-Key": "VOTRE_CLE_API"
      }
    }
  }
}
  1. Redémarrez Antigravity pour appliquer les changements

Note : Antigravity utilise serverUrl au lieu de url pour les serveurs MCP basés sur HTTP.

Claude Code

Créez un fichier .mcp.json à la racine de votre projet :

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

Lancez Claude Code - il détectera automatiquement le serveur MCP.

Claude Desktop

  1. Ouvrez les paramètres de Claude Desktop
  2. Naviguez vers Développeur → Serveurs MCP
  3. Cliquez sur "Ajouter un Serveur" et ajoutez :
{
  "mcpServers": {
    "archyl": {
      "url": "https://api.archyl.com/mcp?apiKey=VOTRE_CLE_API"
    }
  }
}
  1. Redémarrez Claude Desktop

Note : Les connecteurs distants de Claude Desktop ne supportent pas les headers personnalisés, donc la clé API doit être passée en paramètre d'URL.

Cursor

Créez un fichier .cursor/mcp.json dans votre projet :

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

Redémarrez Cursor pour charger le serveur MCP.

OpenAI Codex

Ouvrez ou créez ~/.codex/config.toml et ajoutez :

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

Redémarrez Codex CLI ou IDE pour appliquer les changements.

VS Code

  1. Ouvrez les paramètres VS Code (Cmd/Ctrl + ,)
  2. Recherchez "MCP" et cliquez sur "Modifier dans settings.json"
  3. Ajoutez :
{
  "mcp": {
    "servers": {
      "archyl": {
        "url": "https://api.archyl.com/mcp?apiKey=VOTRE_CLE_API"
      }
    }
  }
}

Warp

  1. Ouvrez Warp et allez dans Paramètres > Serveurs MCP
  2. Cliquez sur "Ajouter un serveur" et collez la configuration :
{
  "archyl": {
    "url": "https://api.archyl.com/mcp",
    "headers": {
      "X-API-Key": "VOTRE_CLE_API"
    }
  }
}
  1. Redémarrez Warp pour appliquer les changements

Windsurf

Ouvrez le fichier de configuration MCP à ~/.codeium/windsurf/mcp_config.json :

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

Redémarrez Windsurf pour appliquer les changements.

Outils Disponibles

Une fois connecté, votre assistant IA peut utiliser ces outils :

Gestion de Projet

Outil Description
list_projects Lister tous vos projets
get_project Obtenir les détails d'un projet
create_project Créer un nouveau projet

Éléments d'Architecture

Outil Description
list_systems Lister les systèmes d'un projet
create_system Créer un nouveau système
list_containers Lister les conteneurs d'un système
create_container Créer un nouveau conteneur
list_components Lister les composants d'un conteneur
create_component Créer un nouveau composant

Relations

Outil Description
list_relationships Lister les relations
create_relationship Créer une relation

Documentation

Outil Description
list_adrs Lister les Architecture Decision Records
create_adr Créer un nouvel ADR
list_docs Lister la documentation
create_doc Créer de la documentation

Exemples de Conversations

Explorer l'Architecture

Vous : "Quels systèmes sont dans mon projet e-commerce ?"

IA : Utilise l'outil list_systems "Votre projet e-commerce a 4 systèmes : Boutique Web, Service de Paiement, Système d'Inventaire et Service de Notification..."

Créer des Éléments

Vous : "Ajoute un nouveau conteneur appelé Redis Cache au système Boutique Web pour le stockage des sessions"

IA : Utilise l'outil create_container "J'ai créé le conteneur Redis Cache dans le système Boutique Web avec la description 'Cache en mémoire pour le stockage des sessions'."

Documentation

Vous : "Crée un ADR pour notre décision d'utiliser PostgreSQL plutôt que MongoDB"

IA : Utilise l'outil create_adr "J'ai créé ADR-001 : Sélection de Technologie de Base de Données, documentant la décision d'utiliser PostgreSQL pour sa conformité ACID et sa flexibilité de requêtes..."

Point de Terminaison

HTTP Streamable (MCP)

https://api.archyl.com/mcp

Utilisez ce point de terminaison pour connecter votre assistant IA à la documentation d'architecture Archyl. Il supporte le protocole de transport HTTP Streamable.

Dépannage

Échec de Connexion

  • Vérifiez que votre clé API est valide
  • Assurez-vous que l'URL du point de terminaison est correcte
  • Vérifiez votre connexion réseau

Échec d'Authentification

  • Pour les outils avec support des headers : Vérifiez que le header X-API-Key est correctement configuré
  • Pour les outils sans support des headers : Vérifiez que le paramètre ?apiKey= est dans l'URL
  • Assurez-vous que votre clé API n'a pas expiré

Outil Non Trouvé

  • Assurez-vous d'utiliser le bon nom d'outil
  • Vérifiez que votre clé API a les permissions requises

Problèmes spécifiques à Antigravity

  • Assurez-vous d'utiliser serverUrl (pas url) pour la configuration
  • L'emplacement du fichier de config est ~/.gemini/antigravity/mcp_config.json

Problèmes spécifiques à OpenAI Codex

  • Assurez-vous que la syntaxe TOML est correcte dans ~/.codex/config.toml
  • Utilisez [mcp_servers.archyl] comme nom de table

Problèmes spécifiques à Warp

  • Naviguez vers Paramètres > Serveurs MCP pour gérer les configurations
  • Redémarrez Warp après avoir modifié la configuration

Bonnes Pratiques

Soyez Spécifique

Quand vous demandez à votre IA de modifier l'architecture, soyez spécifique :

  • Incluez les noms de projets
  • Spécifiez les types d'éléments
  • Fournissez des descriptions

Révisez les Changements

Révisez toujours les éléments créés par l'IA :

  • Vérifiez que les noms et descriptions sont précis
  • Vérifiez que les relations sont correctes
  • Mettez à jour si nécessaire

Utilisez pour l'Exploration

MCP est excellent pour :

  • Explorer rapidement de grandes architectures
  • Générer une documentation initiale
  • Répondre aux questions sur vos systèmes