Server MCP: Parla con la Tua Architettura dai Tuoi Strumenti AI Preferiti

Uso assistenti di codifica AI quotidianamente da più di un anno. Claude Code per refactoring complessi, Cursor per modifiche rapide, GitHub Copilot per l'autocompletamento. Ma c'era sempre un gap frustrante: questi strumenti non potevano vedere la mia documentazione architetturale.

Ogni volta che chiedevo a Claude di "aggiungere un nuovo endpoint al servizio di pagamento", indovinava. Non sapeva che il nostro servizio di pagamento comunica con Stripe, usa Redis per il caching e ha requisiti di sicurezza specifici documentati nei nostri ADR. Passavo più tempo a correggere l'AI che a scrivere codice io stesso.

Oggi chiudiamo quel gap. Archyl ora espone un server MCP (Model Context Protocol) completo con 56 strumenti che danno agli assistenti AI visibilità completa sulla tua architettura.

Cos'è MCP?

Model Context Protocol è lo standard aperto di Anthropic per connettere assistenti AI a strumenti e fonti dati esterne. Pensalo come un adattatore universale tra LLM e i sistemi con cui devono interagire.

Invece di copiare e incollare contesto nei prompt, MCP permette agli assistenti AI di interrogare direttamente i tuoi strumenti. Possono leggere dati, eseguire azioni e rimanere sincronizzati con i tuoi sistemi reali.

E il server MCP di Archyl significa che la tua documentazione architetturale diventa una fonte dati di prima classe per qualsiasi assistente AI.

Cosa Puoi Farci?

Ecco dove diventa entusiasmante. Con il server MCP di Archyl, il tuo assistente AI può:

Interrogare la Tua Architettura

Fai domande naturali e ottieni risposte reali:

• "Quali elementi sono collegati al sistema Processore di Pagamenti?"
• "Da quali container dipende il Servizio Utenti?"
• "Mostrami tutti i sistemi che interagiscono con il nostro database PostgreSQL"
• "Quali ADR influenzano il flusso di autenticazione?"

L'AI non indovina. Interroga la tua architettura reale documentata e restituisce informazioni precise e strutturate.

Navigare il Modello C4

La tua AI comprende l'intera gerarchia:

• Elencare tutti i progetti nella tua organizzazione
• Approfondire da sistemi a container a componenti
• Esplorare relazioni e dipendenze
• Comprendere lo stack tecnologico a ogni livello

Quando chiedi "quali tecnologie usa il Servizio Ordini?", l'AI restituisce lo stack reale documentato, non un'ipotesi allucinata.

Modificare la Documentazione

Questa è la funzionalità killer. Il server MCP supporta operazioni di scrittura:

• Creare nuovi sistemi, container e componenti
• Aggiungere relazioni tra elementi
• Creare e aggiornare ADR
• Scrivere documentazione di progetto
• Definire flussi utente

Chiedi a Claude di "documentare il nuovo servizio di notifica che abbiamo appena costruito" e può creare gli elementi C4, collegarli ai sistemi esistenti e persino redigere un ADR che spiega la decisione di design.

Restare Sincronizzati

L'AI vede sempre lo stato più recente. Nessun contesto obsoleto, nessuna documentazione datata. Quando un collega aggiorna l'architettura, il tuo assistente AI lo vede immediatamente.

56 Strumenti, Una Sola Integrazione

Non abbiamo costruito una proof-of-concept minimale. Il server MCP espone funzionalità complete:

Progetti e Impostazioni: Elencare, ottenere e gestire progetti. Configurare provider AI e impostazioni di discovery.

Modello C4 (Tutti e 4 i Livelli): CRUD completo per sistemi, container, componenti ed elementi di codice. Creare relazioni, gestire overlay, gestire l'intera gerarchia del modello.

Documentazione: Creare e aggiornare documentazione architetturale. Collegare documenti a specifici elementi C4.

ADR: Gestione completa degli Architecture Decision Record. Creare, aggiornare, elencare e collegare ADR agli elementi che influenzano.

Flussi Utente: Definire e visualizzare i percorsi utente attraverso il tuo sistema.

Discovery: Avviare la discovery architetturale con AI sui repository connessi.

Team: Interrogare la struttura del team e l'accesso ai progetti.

Ogni strumento restituisce dati strutturati su cui gli assistenti AI possono ragionare. Niente parsing di HTML, niente scraping di UI, niente integrazioni fragili.

Iniziare in 2 Minuti

Ecco come collegare Claude Code (o qualsiasi strumento compatibile MCP):

Passo 1: Creare una Chiave API

Vai al tuo profilo Archyl, clicca su "Chiavi API" e crea una nuova chiave. Dalle un nome descrittivo come "Claude Code" e seleziona gli ambiti necessari (sola lettura o accesso completo).

Copia la chiave immediatamente — non la vedrai più.

Passo 2: Configurare il Tuo Client MCP

Aggiungi Archyl alla tua configurazione MCP. Per Claude Code, aggiungi questo alle tue impostazioni:

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

Passo 3: Inizia a Parlare con la Tua Architettura

Tutto qui. Chiedi al tuo assistente AI della tua architettura e guardalo recuperare dati reali da Archyl.

Prova questi prompt:

• "Elenca tutti i miei progetti Archyl"
• "Quali sistemi esistono nel progetto Piattaforma E-commerce?"
• "Mostrami le relazioni del Gateway di Pagamento"
• "Crea un nuovo ADR che spiega perché abbiamo scelto PostgreSQL"

Perché Questo È Importante

La documentazione architetturale ha sempre avuto un problema di scopribilità. La scrivi, vive in un wiki o in un diagramma da qualche parte, e poi nessuno la legge. Gli ingegneri chiedono su Slack invece di consultare la documentazione.

MCP cambia il modello di interazione. La documentazione non è qualcosa che vai a leggere — è qualcosa che il tuo assistente AI conosce. Quando chiedi "come funziona l'elaborazione dei pagamenti?", la risposta arriva dalla tua architettura reale, non dai dati di addestramento dell'AI.

Questo ha implicazioni profonde:

L'onboarding diventa istantaneo. I nuovi ingegneri chiedono alla loro AI dell'architettura di sistema e ricevono risposte accurate fin dal primo giorno.

Il contesto è sempre disponibile. Quando scrivi codice, l'AI sa esattamente quali servizi esistono, come si collegano e quali decisioni li hanno plasmati.

La documentazione resta aggiornata. Poiché è usata attivamente, le imprecisioni vengono notate e corrette. La documentazione morta è documentazione che nessuno legge.

I suggerimenti dell'AI sono fondati. Quando Claude suggerisce un design, è informato dalla tua architettura reale, non da pattern generici.

Il Quadro Più Ampio

Stiamo entrando in un'era in cui gli assistenti AI sono collaboratori genuini nello sviluppo software. Ma sono buoni solo quanto il contesto a cui hanno accesso.

La maggior parte delle interazioni AI oggi sono povere di contesto. Incolli del codice, aggiungi una breve descrizione e speri che l'AI capisca il resto. I risultati sono mediocri perché l'AI sta lavorando alla cieca.

Le integrazioni alimentate da MCP ribaltano questo modello. La tua AI ha accesso persistente e interrogabile a tutto ciò di cui ha bisogno: il tuo codice (tramite integrazione repository), la tua architettura (tramite Archyl), le tue issue (tramite integrazioni Jira/Linear), la tua documentazione (tramite integrazioni Notion/Confluence).

L'AI diventa un vero membro del team con accesso alla conoscenza del team.

Il server MCP di Archyl è il nostro contributo a questa visione. La tua architettura non dovrebbe essere chiusa in uno strumento di diagrammi. Dovrebbe essere accessibile a ogni strumento che il tuo team usa, inclusi i tuoi assistenti AI.

Cosa Succede Dopo

Questa è la versione 1. Ecco cosa stiamo costruendo:

Suggerimenti proattivi: Il server MCP potrebbe monitorare le modifiche architetturali e suggerire aggiornamenti alla documentazione.

Link di riferimento incrociato: Collegare ADR a commit specifici, collegare documentazione a eventi CI/CD, creare una rete di conoscenza interconnessa.

Query personalizzate: Definire query specifiche dell'organizzazione come "mostrami tutti i servizi del team pagamenti."

Logging di audit: Tracciare ogni interazione MCP per conformità e debugging.

Provalo Ora

Il server MCP è disponibile oggi su tutti i piani Archyl. Se stai già usando Claude Code, Cursor o un altro strumento compatibile MCP, puoi connetterti in pochi minuti.

Crea una chiave API, aggiungi la configurazione e inizia a parlare con la tua architettura.

E se non stai ancora usando Archyl, iscriviti gratuitamente e scopri come funziona la documentazione architetturale con AI. Collega un repository, esegui la discovery e poi collega il tuo assistente AI preferito.

La tua architettura è troppo importante per restare chiusa in diagrammi statici. Lascia che i tuoi assistenti AI la esplorino.

Vuoi saperne di più sulle capacità AI di Archyl? Dai un'occhiata al nostro post sulla Discovery Architetturale con AI, o inizia dalle basi con la nostra Introduzione al Modello C4.