Documentazione · MCP

Server MCP di vetkit

Dai al tuo agente di coding un auditor del codice. Il server MCP di vetkit permette a Claude Code — e a qualsiasi altro client Model Context Protocol — di collegare repository, eseguire audit e leggere rilevamenti e report.

Installazione in Claude Code

$ claude mcp add vetkit -e VETKIT_API_KEY=vk_live_... -- npx -y @vetkit/mcp

Poi chiedi al tuo agente qualcosa come “Esegui l’audit di acme/payments-api e dimmi cosa correggere per primo.” Esegui /mcp in Claude Code per verificare che vetkit sia connesso.

Requisiti

Node.js 20.3 o successivo, con npx nel tuo PATH.
Un account vetkit con la GitHub App installata sui repository che vuoi sottoporre ad audit.
Una chiave API di vetkit (passaggio successivo).

Crea una chiave API

Apri Impostazioni → Chiavi API nell’app vetkit. Solo i proprietari e gli amministratori dell’organizzazione possono gestire le chiavi.
Dai alla chiave un nome che indichi dove verrà usata, ad esempio “Claude Code — laptop”.
Scegli gli ambiti. Per usare tutte le funzionalità MCP scegli repos:read, repos:write, audits:read, audits:write, findings:read e reports:read. Per un agente in sola lettura, escludi repos:write e audits:write.
Facoltativamente, imposta una scadenza e un limite di frequenza al minuto (predefinito 60, fino a 600).
Copia il segreto. Ha la forma vk_live_… e viene mostrato una sola volta; vetkit ne memorizza solo un hash.

Rotazione e revoca

La rotazione di una chiave genera un nuovo segreto e mantiene valido quello vecchio per 24 ore, così hai il tempo di distribuire quello nuovo. La revoca ha effetto immediato — la richiesta successiva restituisce 401 API_KEY_REVOKED.

Installazione

Claude Code

Terminale

$ claude mcp add vetkit -e VETKIT_API_KEY=vk_live_... -- npx -y @vetkit/mcp

Aggiungi --scope user per rendere vetkit disponibile in tutti i progetti anziché solo in quello corrente.

Claude Desktop

Apri Settings → Developer → Edit Config e aggiungi vetkit a claude_desktop_config.json, poi riavvia Claude Desktop:

claude_desktop_config.json

{  "mcpServers": {    "vetkit": {      "command": "npx",      "args": ["-y", "@vetkit/mcp"],      "env": { "VETKIT_API_KEY": "vk_live_..." }    }  }}

Cursor

Aggiungi lo stesso blocco a ~/.cursor/mcp.json (globale) o a .cursor/mcp.json in un progetto. Non fare il commit di una configurazione di progetto che contiene la tua chiave.

~/.cursor/mcp.json

{  "mcpServers": {    "vetkit": {      "command": "npx",      "args": ["-y", "@vetkit/mcp"],      "env": { "VETKIT_API_KEY": "vk_live_..." }    }  }}

Altri client MCP

Funziona con qualsiasi client in grado di avviare un server stdio: esegui npx -y @vetkit/mcp con VETKIT_API_KEY nel suo ambiente. Puoi anche installare il pacchetto globalmente ed eseguire direttamente il binario vetkit-mcp.

Installazione globale

$ npm install -g @vetkit/mcp$ VETKIT_API_KEY=vk_live_... vetkit-mcp

Configurazione

Il server si configura interamente tramite variabili d’ambiente.

Variabile	Obbligatoria	Descrizione
`VETKIT_API_KEY`	Sì	La tua chiave API, `vk_live_…` o `vk_test_…`.
`VETKIT_API_URL`	No	URL di base dell’API. Predefinito `https://api.vetkit.dev`. Deve essere HTTPS; HTTP semplice è accettato solo per `localhost`.
`VETKIT_ORG_ID`	No	ID dell’organizzazione. Ogni chiave API appartiene esattamente a un’organizzazione, che viene usata per impostazione predefinita, quindi raramente ti servirà.
`VETKIT_APP_URL`	No	URL della web app usato per i link agli audit. Predefinito `https://app.vetkit.dev`.

Strumenti

Ogni strumento restituisce testo leggibile e tutti gli strumenti tranne vetkit_get_report restituiscono anche contenuto strutturato tipizzato. Gli strumenti includono le annotazioni MCP, così i client possono approvare automaticamente quelli in sola lettura. Nessuno strumento elimina alcunché.

vetkit_list_repos

sola lettura

Elenca i repository collegati alla tua organizzazione, con il voto e il punteggio dell’ultimo audit.

Ambiti: repos:read

Argomento	Tipo	Descrizione
`limit`	number	Dimensione della pagina, 1–100. Predefinito 25.
`cursor`	string	Il valore nextCursor della pagina precedente.

Argomenti di esempio

{ "limit": 10 }

vetkit_connect_repo

scrittura

Collega un repository GitHub. Se la GitHub App di vetkit non è ancora installata per il proprietario, restituisce l’outcome "installation_required" con un URL di installazione da aprire nel browser.

Ambiti: repos:write

Argomento	Tipo	Descrizione
`url`obbligatorio	string	URL GitHub (https://github.com/owner/name) o "owner/name".

Argomenti di esempio

{ "url": "https://github.com/acme/payments-api" }

vetkit_run_audit

scrittura

Avvia un audit e, per impostazione predefinita, attende che termini inviando notifiche di avanzamento. Se necessario, collega prima il repository. Restituisce voto, punteggio e conteggi dei rilevamenti.

Ambiti: repos:read, audits:write, audits:read (+ repos:write per il collegamento automatico)

Argomento	Tipo	Descrizione
`repo`obbligatorio	string	ID del repository, "owner/name" o un URL GitHub — incluso /tree/<branch>.
`ref`	string	Branch, tag o SHA del commit. Per impostazione predefinita usa il ref nell’URL, altrimenti il branch predefinito.
`wait`	boolean	Attende uno stato finale. Predefinito true.
`timeoutSeconds`	number	Attesa massima, 10–1800. Predefinito 600. Dopo un timeout l’audit continua a essere eseguito.

Argomenti di esempio

{ "repo": "acme/payments-api", "ref": "main" }

vetkit_get_audit

sola lettura

Restituisce stato, voto, punteggio, conteggi dei rilevamenti e avanzamento per analizzatore di un audit.

Ambiti: audits:read

Argomento	Tipo	Descrizione
`auditId`obbligatorio	uuid	L’ID dell’audit restituito da vetkit_run_audit.

Argomenti di esempio

{ "auditId": "0192f3a4-5b6c-7d8e-9f01-23456789abcd" }

vetkit_list_findings

sola lettura

Elenca i rilevamenti di un audit, dal più grave. Restituisce una tabella compatta come testo e tutti i dettagli — messaggio, snippet oscurato, correzione, riferimenti — come contenuto strutturato.

Ambiti: findings:read

Argomento	Tipo	Descrizione
`auditId`obbligatorio	uuid	L’audit da leggere.
`severity`	string[]	CRITICAL, HIGH, MEDIUM, LOW o INFO.
`category`	string[]	SECURITY, SECRETS, DEPENDENCIES, QUALITY, HYGIENE o AI_SIGNAL.
`status`	string	NEW (introdotto dopo l’audit precedente) o EXISTING.
`limit`	number	Dimensione della pagina, 1–100. Predefinito 25.
`cursor`	string	Il valore nextCursor della pagina precedente.

Argomenti di esempio

{ "auditId": "0192f3a4-…", "severity": ["CRITICAL", "HIGH"] }

vetkit_get_report

sola lettura

Restituisce il report di un audit concluso: Markdown leggibile, un riepilogo JSON con i punteggi per categoria e il confronto con l’audit precedente, oppure SARIF 2.1.0.

Ambiti: reports:read

Argomento	Tipo	Descrizione
`auditId`obbligatorio	uuid	L’audit da leggere.
`format`	string	markdown (predefinito), json o sarif.
`maxChars`	number	Tronca l’output oltre questo numero di caratteri, 2.000–500.000. Predefinito 40.000.

Argomenti di esempio

{ "auditId": "0192f3a4-…", "format": "markdown" }

Audit di lunga durata

La maggior parte degli audit termina in pochi minuti. vetkit_run_audit controlla lo stato a intervalli di pochi secondi e invia notifiche di avanzamento durante l’attesa. Alcuni client annullano le chiamate agli strumenti dopo un tempo fisso — Claude Code, ad esempio, rispetta MCP_TOOL_TIMEOUT. Se il tuo lo fa, passa "wait": false e controlla lo stato con vetkit_get_audit. Quando timeoutSeconds scade, l’audit continua a essere eseguito e lo strumento restituisce "outcome": "still_running".

Errori

Gli errori dell’API vengono restituiti come risultati dello strumento con isError: true e includono lo stato HTTP, il codice di errore vetkit, il messaggio, l’ID della richiesta e un suggerimento.

401 API_KEY_INVALID, API_KEY_REVOKED, API_KEY_EXPIRED — crea o ruota una chiave, aggiorna VETKIT_API_KEY e riavvia il server.
403 INSUFFICIENT_SCOPE — alla chiave manca un ambito richiesto dallo strumento.
409 AUDIT_CONCURRENCY_LIMIT e 429 RATE_LIMITED — attendi e riprova; il suggerimento include il tempo di attesa quando l’API invia Retry-After.
INSTALLATION_REQUIRED viene restituito come risultato normale con l’URL di installazione della GitHub App, non come errore.

Note di sicurezza

Tratta la chiave API come una password. Dà accesso agli audit e ai rilevamenti della tua organizzazione, inclusi i repository privati. Conservala nella configurazione env del tuo client MCP, mai in file di cui fai il commit. Concedi solo gli ambiti necessari, imposta una scadenza e revocala dall’app se viene esposta.
La chiave viene inviata solo a VETKIT_API_URL, come header Authorization: Bearer su HTTPS. Il server non la scrive mai nei log né la include nei messaggi di errore.
Il server comunica tramite MCP solo su stdio. Non apre porte di rete e scrive log solo su stderr.
Gli snippet dei rilevamenti vengono oscurati prima che vetkit li memorizzi; i valori dei segreti non vengono mai restituiti.
I testi di report e rilevamenti provengono dal repository sottoposto ad audit (percorsi dei file, messaggi). Trattali come input non attendibile, come qualsiasi altro output di uno strumento — un repository malevolo potrebbe tentare di inserire istruzioni rivolte al tuo agente.

Preferisci HTTP diretto? Tutto ciò che fa il server MCP è disponibile tramite l’API REST.