I tool MCP come API Contracts: documenta cosa possono fare i tuoi agenti
Qualche mese fa abbiamo rilasciato gli API Contracts: specifiche OpenAPI, gRPC, GraphQL e AsyncAPI, collegate direttamente agli elementi C4 che le implementano e le consumano. L'idea era semplice — la descrizione precisa e leggibile da una macchina di un'interfaccia va dentro la tua architettura, non in una pagina Notion che nessuno aggiorna.
Restava un'interfaccia che non avevamo coperto. La più recente. Quella che i tuoi servizi espongono sempre più, non ad altri servizi, ma agli agenti IA: MCP.
Un server MCP pubblica un insieme di tool — ciascuno con un nome, una descrizione e un JSON Schema per i suoi input. Questo è un contratto. È il contratto che decide cosa un agente ha il permesso di fare al tuo sistema. E fino a oggi era completamente invisibile nella tua documentazione di architettura.
Non più. MCP è ora un tipo di API Contract a tutti gli effetti in Archyl — il quinto, accanto a HTTP, gRPC, GraphQL e AsyncAPI.
La parte difficile: i tool MCP non vivono in un file
Gli altri quattro tipi di contratto condividono un presupposto — esiste un file di spec in un repo. openapi.yaml. schema.graphql. Punti Archyl su di esso e lo renderizziamo.
MCP rompe questo schema. I tool di un server MCP sono definiti nel codice, e l'elenco completo e autorevole esiste solo a runtime, quando un client chiama tools/list e riceve lo schema di ogni tool. Non c'è un mcp.yaml universale da puntare.
Così abbiamo costruito due strade.
Due modi per aggiungere un contratto MCP
Incollalo. Se hai già il tuo output di tools/list, incollalo. Archyl lo valida e renderizza ogni tool — la sua descrizione e i suoi parametri di input in una tabella leggibile.
Oppure dacci semplicemente la URL. Indica ad Archyl dove si trova il tuo server MCP, aggiungi facoltativamente un token di accesso (come header o come parametro URL) e clicca su Scopri i tool. Archyl si connette, esegue l'handshake e importa automaticamente ogni tool e parametro. Niente copia-incolla, nessun file mantenuto a mano.
Come funziona la scoperta live — e perché è sicura
La scoperta avviene nel tuo browser, non sui nostri server. Quando clicchi su Scopri i tool, il tuo browser parla direttamente con il tuo server MCP.
Questa scelta conta:
- Il tuo token non lascia mai il tuo browser. Archyl memorizza i tool scoperti e i dettagli di connessione — la URL, il transport, dove va il token — ma mai il token stesso.
- Nessun accesso lato server alla tua rete. Poiché la chiamata parte dalla tua macchina, non può essere puntata ai servizi interni di qualcun altro. L'intera categoria di rischi tipo SSRF semplicemente non esiste qui.
- Raggiunge localhost e i server privati. Stai testando un server che gira sul tuo portatile o dentro la tua rete? Funziona, perché è il tuo browser a vederlo.
L'unico compromesso è il CORS: un server di terze parti deve consentire l'origine di Archyl affinché il tuo browser possa leggere la risposta. Per i server che controlli è una riga di configurazione; per gli altri, l'opzione "incolla" è sempre disponibile.
Collegato alla tua architettura, come ogni altro contratto
Una volta inserito, un contratto MCP si comporta come gli altri. Collegalo al container o al componente che ospita il server. Sfoglia ogni tool e il suo schema di input. Ri-scoprilo quando il server cambia. Compare accanto ai tuoi contratti REST e GraphQL, perché per gli agenti che lo chiamano è un'API altrettanto reale.
Questo trasforma il tuo contratto MCP in qualcosa di davvero nuovo: una mappa di ciò che i tuoi agenti IA hanno il permesso di fare a una determinata parte del tuo sistema — documentata, collegata e revisionabile.
Lo usiamo su noi stessi
Archyl è esso stesso un server MCP — 178 tool che ti permettono di pilotare la tua architettura da Claude Code, Cursor o qualsiasi client MCP. Il primo contratto MCP che abbiamo creato è stato il nostro: puntare Archyl sul proprio endpoint, scoprire tutti i 178 tool, collegarlo alla piattaforma. La nostra superficie di agente ora documenta sé stessa.
Provalo
Apri un progetto, vai su API Contracts, creane uno nuovo e scegli MCP. Incolla il tuo tools/list, oppure inserisci una URL e premi Scopri i tool.
I tuoi servizi parlano già con gli agenti. Ora la tua architettura sa cosa si dicono.