Server MCP - Archyl Docs

Collega assistenti AI come Claude, Cursor e VS Code alla tua documentazione architetturale

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ò:

  • Elencare e navigare i tuoi progetti
  • Creare e modificare elementi architetturali
  • Generare documentazione
  • Rispondere a domande sulla tua architettura

Strumenti 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

Il server MCP richiede una chiave API per l'autenticazione. 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.

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

Strumenti Disponibili

Una volta connesso, il tuo assistente AI può utilizzare questi strumenti:

Gestione Progetti

Strumento Descrizione
list_projects Elenca tutti i tuoi progetti
get_project Ottieni i dettagli di un progetto
create_project Crea un nuovo progetto

Elementi Architetturali

Strumento Descrizione
list_systems Elenca i sistemi in un progetto
create_system Crea un nuovo sistema
list_containers Elenca i container in un sistema
create_container Crea un nuovo container
list_components Elenca i componenti in un container
create_component Crea un nuovo componente

Relazioni

Strumento Descrizione
list_relationships Elenca le relazioni
create_relationship Crea una relazione

Documentazione

Strumento Descrizione
list_adrs Elenca gli Architecture Decision Record
create_adr Crea un nuovo ADR
list_docs Elenca la documentazione
create_doc Crea documentazione

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

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 ?apiKey= sia nell'URL
  • Assicurati che la tua chiave API non sia scaduta

Strumento Non Trovato

  • Assicurati di usare il nome corretto dello strumento
  • Verifica che la tua chiave API abbia i permessi necessari

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