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 :

• Parcourir et interroger vos projets ainsi que l'intégralité de leur modèle C4
• Créer et modifier des éléments d'architecture, des relations et des diagrammes
• Lire et écrire des ADR, de la documentation, des contrats d'API et des canaux d'événements
• Vérifier les règles de conformité, les scores de dérive, les métriques DORA et la propriété avant d'écrire du code
• Suivre les releases, les demandes de changement, les commentaires et l'historique

Clients 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

Clé API (recommandé)

La plupart des clients s'authentifient avec une clé API. 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.

Les portées de la clé déterminent ce que l'assistant peut faire : une clé en lecture seule peut appeler tous les outils list_* et get_*, tandis que create_*, update_*, delete_* et import_dsl nécessitent une clé avec la portée écriture. Confier à votre agent une clé en lecture seule est le moyen le plus simple de le laisser explorer votre architecture sans pouvoir la modifier.

OAuth 2.1

Le serveur implémente également OAuth 2.1 avec enregistrement dynamique des clients, pour les clients qui se connectent via une authentification dans le navigateur plutôt qu'avec une clé collée (les portées mcp:read et mcp:write reflètent celles des clés API ci-dessus). Pointez un tel client vers le même point de terminaison et il découvrira le flux automatiquement via :

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

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

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

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

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

Référence des outils

Le serveur expose 189 outils. Ils suivent une convention de nommage prévisible, ce qui permet généralement à un assistant de deviner le bon :

La plupart des outils à portée projet prennent un projectId ; les outils à portée élément prennent un elementId ainsi qu'un elementType (le niveau C4 : 1 = système, 2 = conteneur, 3 = composant, 4 = code). Demandez à votre assistant d'appeler list_projects en premier — il y récupérera les identifiants dont il a besoin.

Votre client découvre cette liste automatiquement via tools/list, elle reste donc toujours synchronisée avec le serveur. Les tableaux ci-dessous sont destinés aux humains qui décident quoi demander.

Profils d'outils

189 outils, c'est plus que ce dont un agent de code a besoin pour une tâche délimitée — et les annoncer tous coûte du contexte. Ajoutez ?profile=coding à l'URL MCP (ou envoyez un en-tête X-Archyl-Tool-Profile: coding) pour réduire la surface à 16 outils : le contexte ciblé par tâche, la boucle de session de travail du harness et les vérifications de conformité/diff. Omettez le paramètre (ou utilisez profile=full) pour le catalogue complet.

Contexte pour l'agent (4)

Commencez ici : ces outils donnent à un assistant une vision d'ensemble de l'architecture en un seul appel, plutôt qu'en plusieurs.

Sessions de travail Harness (8)

La boucle de travail gouvernée pour les agents de code : déclarez une unité de travail pour obtenir un contexte ciblé et des verrous consultatifs, signalez que la session est active pendant le travail, puis terminez avec un résultat qui peut ouvrir une demande de changement d'architecture. Plus la mémoire de projet : mémorisez des faits pour les prochains intervenants, retrouvez ce que les sessions précédentes ont appris.

Projets (7)

Organisations et équipes (5)

Éléments C4 (15)

Systèmes (niveau 1), conteneurs (niveau 2), composants (niveau 3) et éléments de code (niveau 4).

Relations (4)

Disposition du diagramme et calques (5)

Documentation (11)

Architecture Decision Records (6)

Contrats d'API (8)

Contrats OpenAPI, gRPC, GraphQL, AsyncAPI et outils MCP.

Canaux d'événements (8)

Flux et tableaux blancs (8)

Commentaires et discussions (11)

Propriété (6)

Technologies et radar (10)

Releases et environnements (10)

Demandes de changement d'architecture (6)

Règles de conformité (9)

Détection de dérive (4)

Métriques DORA, ROI et prédictions (4)

Historique et voyage dans le temps (5)

Analyses (3)

Marketplace et widgets (15)

Webhooks (7)

Architecture à l'échelle de l'organisation (9)

Vues inter-projets et artefacts au niveau de l'organisation.

Architecture as Code (1)

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

Avant d'écrire du code

Vous : "Je m'apprête à ajouter une limitation de débit au flux de commande. Que dois-je savoir ?"

IA : Utilise find_relevant_context et impact_of "La commande touche l'API Gateway et le service Orders. Modifier la gateway affecte 6 conteneurs en aval. L'ADR-014 impose déjà Redis pour la limitation de débit, et une règle de conformité interdit toute nouvelle dépendance vers l'ancien Session store..."

Vérification de gouvernance

Vous : "Sommes-nous en train de dériver par rapport à l'architecture documentée ?"

IA : Utilise get_drift_score et run_conformance_check "Le score de dérive est de 82 % (contre 91 % le mois dernier). Deux violations : le service Search appelle directement la base de données Orders, et Payments utilise un client HTTP non approuvé..."

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 — consultez la référence des outils, ou demandez à votre client de rafraîchir sa liste d'outils
• Certains clients mettent tools/list en cache ; redémarrez le client après une mise à jour

Outils d'Écriture Rejetés

• create_*, update_*, delete_* et import_dsl nécessitent une clé API avec la portée écriture — une clé en lecture seule ne peut appeler que list_* et get_*
• Vérifiez votre plan d'abonnement : certaines fonctionnalités (webhooks, connexions marketplace, exécutions d'agents managés) sont réservées à certains plans

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