Server MCP

Archyl fornisce un server Model Context Protocol (MCP) che consente agli assistenti AI di interagire con la tua documentazione architetturale. Questo permette un'esplorazione e documentazione dell'architettura potenziate dall'AI.

Cos'è MCP?

Il Model Context Protocol (MCP) è un protocollo aperto che consente agli assistenti AI di accedere in modo sicuro a strumenti e fonti di dati esterne. Con il server MCP di Archyl, il tuo assistente AI può:

• Esplorare e interrogare i tuoi progetti e il loro modello C4 completo
• Creare e modificare elementi architetturali, relazioni e diagrammi
• Leggere e scrivere ADR, documentazione, contratti API e canali di eventi
• Verificare regole di conformità, punteggi di drift, metriche DORA e ownership prima di scrivere codice
• Tracciare release, richieste di modifica, commenti e cronologia

Client supportati

Il server MCP di Archyl funziona con:

• Antigravity - IDE potenziato dall'AI di Google
• Claude Code - Strumento CLI di Anthropic
• Claude Desktop - Applicazione desktop di Claude
• Cursor - Editor di codice AI-first
• OpenAI Codex - Assistente di programmazione AI di OpenAI
• VS Code - Con GitHub Copilot Chat
• Warp - Terminale moderno con integrazione AI
• Windsurf - IDE potenziato dall'AI di Codeium

Autenticazione

Chiave API (consigliata)

La maggior parte dei client si autentica con una chiave API. A seconda dello strumento che utilizzi:

• Strumenti con supporto header (Claude Code, Cursor, Warp, Windsurf, Antigravity): Usa l'header X-API-Key
• Strumenti senza supporto header (Claude Desktop, VS Code, OpenAI Codex): Usa il parametro query ?apiKey=YOUR_API_KEY nell'URL

Genera una chiave API dalla pagina Profilo → Chiavi API.

Gli scope della chiave determinano cosa può fare l'assistente: una chiave in sola lettura può chiamare tutti gli strumenti list_* e get_*, mentre create_*, update_*, delete_* e import_dsl richiedono una chiave con scope di scrittura. Fornire al tuo agente una chiave in sola lettura è il modo più semplice per lasciargli esplorare la tua architettura senza che possa modificarla.

OAuth 2.1

Il server implementa anche OAuth 2.1 con registrazione dinamica dei client, per i client che si connettono tramite accesso dal browser invece che con una chiave incollata (gli scope mcp:read e mcp:write rispecchiano gli scope delle chiavi API descritti sopra). Punta un client di questo tipo allo stesso endpoint e scoprirà automaticamente il flusso tramite:

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

Configurazione

Antigravity

1. Apri Antigravity e clicca sul menu "..." nel pannello Agent
2. Seleziona "MCP Servers" > "Manage MCP Servers" > "View raw config"
3. Aggiungi a ~/.gemini/antigravity/mcp_config.json:

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

4. Riavvia Antigravity per applicare le modifiche

Nota: Antigravity utilizza serverUrl invece di url per i server MCP basati su HTTP.

Claude Code

Crea un file .mcp.json nella root del tuo progetto:

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

Avvia Claude Code - rileverà automaticamente il server MCP.

Claude Desktop

1. Apri le impostazioni di Claude Desktop
2. Vai su Developer → MCP Servers
3. Clicca su "Add Server" e aggiungi:

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

4. Riavvia Claude Desktop

Nota: I connettori remoti di Claude Desktop non supportano header personalizzati, quindi la chiave API deve essere passata come parametro query nell'URL.

Cursor

Crea un file .cursor/mcp.json nel tuo progetto:

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

Riavvia Cursor per caricare il server MCP.

OpenAI Codex

Apri o crea ~/.codex/config.toml e aggiungi:

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

Riavvia Codex CLI o IDE per applicare le modifiche.

VS Code

1. Apri le impostazioni di VS Code (Cmd/Ctrl + ,)
2. Cerca "MCP" e clicca su "Edit in settings.json"
3. Aggiungi:

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

Warp

1. Apri Warp e vai su Settings > MCP Servers
2. Clicca su "Add Server" e incolla la configurazione:

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

3. Riavvia Warp per applicare le modifiche

Windsurf

Apri il file di configurazione MCP in ~/.codeium/windsurf/mcp_config.json:

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

Riavvia Windsurf per applicare le modifiche.

Riferimento degli strumenti

Il server espone 189 strumenti. Seguono uno schema di denominazione prevedibile, quindi un assistente riesce di solito a indovinare quello giusto:

La maggior parte degli strumenti con ambito progetto richiede un projectId; gli strumenti con ambito elemento richiedono un elementId più un elementType (il livello C4: 1 = sistema, 2 = container, 3 = componente, 4 = codice). Chiedi al tuo assistente di chiamare prima list_projects — da lì recupererà gli ID di cui ha bisogno.

Il tuo client scopre automaticamente questo elenco tramite tools/list, quindi è sempre allineato con il server. Le tabelle seguenti servono agli umani per decidere cosa chiedere.

Profili di strumenti

189 strumenti sono più di quanto serva a un agente di codifica per un compito delimitato — annunciarli tutti costa contesto. Aggiungi ?profile=coding all'URL MCP (o invia l'header X-Archyl-Tool-Profile: coding) per ridurre la superficie a 16 strumenti: contesto mirato al compito, il ciclo di sessioni di lavoro del harness e i controlli di conformità/diff. Ometti il parametro (o usa profile=full) per il catalogo completo.

Contesto per l'agente (4)

Inizia da qui: questi strumenti danno a un assistente il quadro architetturale in una sola chiamata, invece che in molte.

Sessioni di lavoro Harness (8)

Il ciclo di lavoro governato per gli agenti di codifica: dichiara un'unità di lavoro per ottenere contesto mirato e lock consultivi, invia un heartbeat durante il lavoro e concludi con un esito che può aprire una richiesta di modifica dell'architettura. In più la memoria di progetto: memorizza fatti per chi lavorerà dopo e richiama ciò che le sessioni precedenti hanno appreso.

Progetti (7)

Organizzazioni e team (5)

Elementi C4 (15)

Sistemi (livello 1), container (livello 2), componenti (livello 3) ed elementi di codice (livello 4).

Relazioni (4)

Layout dei diagrammi e overlay (5)

Documentazione (11)

Architecture Decision Record (6)

Contratti API (8)

Contratti OpenAPI, gRPC, GraphQL, AsyncAPI e per strumenti MCP.

Canali di eventi (8)

Flussi e lavagne (8)

Commenti e discussioni (11)

Ownership (6)

Tecnologie e radar (10)

Release e ambienti (10)

Richieste di modifica architetturale (6)

Regole di conformità (9)

Rilevamento del drift (4)

Metriche DORA, ROI e previsioni (4)

Cronologia e time travel (5)

Insight (3)

Marketplace e widget (15)

Webhook (7)

Architettura a livello di organizzazione (9)

Viste cross-progetto e artefatti a livello di organizzazione.

Architecture as code (1)

Esempi di Conversazione

Esplorare l'Architettura

Tu: "Quali sistemi ci sono nel mio progetto e-commerce?"

AI: Usa lo strumento list_systems "Il tuo progetto e-commerce ha 4 sistemi: Web Store, Payment Service, Inventory System e Notification Service..."

Creare Elementi

Tu: "Aggiungi un nuovo container chiamato Redis Cache al sistema Web Store per lo storage delle sessioni"

AI: Usa lo strumento create_container "Ho creato il container Redis Cache nel sistema Web Store con la descrizione 'Cache in-memory per lo storage delle sessioni'."

Documentazione

Tu: "Crea un ADR per la nostra decisione di usare PostgreSQL invece di MongoDB"

AI: Usa lo strumento create_adr "Ho creato l'ADR-001: Selezione Tecnologia Database, documentando la decisione di usare PostgreSQL per la sua conformità ACID e flessibilità nelle query..."

Prima di scrivere codice

Tu: "Sto per aggiungere il rate limiting al flusso di checkout. Cosa dovrei sapere?"

AI: Usa find_relevant_context e impact_of "Il checkout coinvolge l'API Gateway e il servizio Orders. Modificare il gateway impatta 6 container a valle. L'ADR-014 impone già Redis per il throttling e una regola di conformità vieta nuove dipendenze dal vecchio Session store..."

Verifica di governance

Tu: "Ci stiamo allontanando dall'architettura documentata?"

AI: Usa get_drift_score e run_conformance_check "Il punteggio di drift è 82% (in calo dal 91% del mese scorso). Due violazioni: il servizio Search chiama direttamente il database Orders e Payments usa un client HTTP non approvato..."

Endpoint

Streamable HTTP (MCP)

https://api.archyl.com/mcp

Usa questo endpoint per connettere il tuo assistente AI alla documentazione architetturale di Archyl. Supporta il protocollo di trasporto Streamable HTTP.

Risoluzione Problemi

Connessione Fallita

• Verifica che la tua chiave API sia valida
• Assicurati che l'URL dell'endpoint sia corretto
• Controlla la tua connessione di rete

Autenticazione Fallita

• Per strumenti con supporto header: Verifica che l'header X-API-Key sia impostato correttamente
• Per strumenti senza supporto header: Verifica che il parametro query ?apiKey= sia nell'URL
• Assicurati che la tua chiave API non sia scaduta

Strumento Non Trovato

• Assicurati di usare il nome corretto dello strumento — consulta il riferimento degli strumenti, oppure chiedi al tuo client di aggiornare la sua lista di strumenti
• Alcuni client mettono in cache tools/list; riavvia il client dopo un aggiornamento

Strumenti di Scrittura Rifiutati

• create_*, update_*, delete_* e import_dsl richiedono una chiave API con scope di scrittura — una chiave in sola lettura può chiamare solo list_* e get_*
• Controlla il tuo piano di abbonamento: alcune funzionalità (webhook, connessioni al marketplace, esecuzioni di agent gestiti) dipendono dal piano

Problemi Specifici di Antigravity

• Assicurati di usare serverUrl (non url) nella configurazione
• La posizione del file di configurazione è ~/.gemini/antigravity/mcp_config.json

Problemi Specifici di OpenAI Codex

• Assicurati che la sintassi TOML sia corretta in ~/.codex/config.toml
• Usa [mcp_servers.archyl] come nome della tabella

Problemi Specifici di Warp

• Vai su Settings > MCP Servers per gestire le configurazioni
• Riavvia Warp dopo aver modificato la configurazione

Best Practice

Sii Specifico

Quando chiedi al tuo AI di modificare l'architettura, sii specifico:

• Includi i nomi dei progetti
• Specifica i tipi di elemento
• Fornisci descrizioni

Revisiona le Modifiche

Revisiona sempre gli elementi creati dall'AI:

• Verifica che nomi e descrizioni siano accurati
• Controlla che le relazioni siano corrette
• Aggiorna se necessario

Usa per l'Esplorazione

MCP è ottimo per:

• Esplorare rapidamente architetture complesse
• Generare documentazione iniziale
• Rispondere a domande sui tuoi sistemi