Server MCP

Dove nel portale: API reference › Tools (https://<your-domain>/apidoc) mostra l'endpoint e gli snippet per il client; le chiavi vengono create in API keys (/api-keys). Non ci sono impostazioni nell'amministrazione: l'endpoint fa parte del pannello.

Descrizione

Il Model Context Protocol (MCP) consente a un assistente IA di richiamare strumenti. NexCMP offre un endpoint MCP su https://<your-domain>/mcp. Ogni operazione API pubblica diventa un singolo strumento (vm_list, vm_start, billing_wallet, ...), permettendo a un cliente di chiedere al proprio assistente "quali delle mie VM sono in esecuzione?" o "arresta la VM di staging". L'assistente agisce esclusivamente con la chiave API e i permessi del cliente stesso.

Configurare NexCMP con l'IA?

Questa pagina riguarda l'endpoint MCP del cliente (/mcp). Per consentire a un assistente IA di configurare il tuo pannello come amministratore, consulta Configure with AI (endpoint /mcp/admin, chiavi admin ak_).

Requisiti

Elemento	Requisito
Server	Nulla da installare: l'endpoint è gestito dal pannello ed è raggiungibile ovunque si trovi il pannello stesso. Il tuo reverse proxy deve inoltrare `/mcp` al pannello.
Cliente	Una API key (`vk_...`) con gli ambiti (scopes) necessari all'assistente.
Client	Un client MCP che supporta il trasporto Streamable HTTP e un'intestazione `Authorization` personalizzata: Claude Code, Claude Desktop (tramite il bridge `mcp-remote`), Cursor, VS Code con modalità agente Copilot e simili.
Versioni del protocollo	2025-11-25, 2025-06-18 e 2025-03-26.

Prepara l'infrastruttura

Nulla, oltre ad assicurarsi che https://<your-domain>/mcp non sia bloccato da un firewall o da una regola di proxy. Un client MCP basato su browser proveniente da un'origine diversa viene rifiutato a meno che tale origine non sia consentita; i client da riga di comando e desktop non inviano alcuna intestazione Origin e funzionano così come sono.

Connessione (lato cliente)

Crea una chiave API nel portale (API keys › Create key) limitandola solo agli ambiti che vuoi siano usati dall'assistente, con una breve scadenza e, se possibile, una restrizione IP.

Aggiungi il server al tuo client. Sostituisci cloud.example.com e la chiave.

Claude Code

bash

claude mcp add --transport http cloud https://cloud.example.com/mcp \
  --header "Authorization: Bearer vk_XXXX"

Cursor (~/.cursor/mcp.json o .cursor/mcp.json; imposta CLOUD_API_KEY nell'ambiente da cui si avvia Cursor):

json

{
  "mcpServers": {
    "cloud": {
      "url": "https://cloud.example.com/mcp",
      "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
    }
  }
}

Claude Desktop (richiede Node.js 18+; claude_desktop_config.json), tramite il bridge mcp-remote:

json

{
  "mcpServers": {
    "cloud": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
      "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
    }
  }
}

Scrivi l'intestazione senza alcuno spazio dopo i due punti e inserisci l'intero valore nella variabile d'ambiente, come indicato sopra.

Riavvia il client e chiedigli di elencare i tuoi strumenti.

Verifica la connessione senza un client:

bash

curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Come funziona

Elemento	Dettaglio
Endpoint	`POST /mcp` con un messaggio JSON-RPC 2.0; la risposta è `application/json`. `GET /mcp` risponde con 405 (nessun flusso da server a client); `DELETE /mcp` termina la sessione.
Autenticazione	Solo `Authorization: Bearer vk_...` (i token di sessione, i cookie e le chiavi di amministrazione vengono rifiutati con un errore 401 e un'intestazione `WWW-Authenticate: Bearer`).
Sessione	`Mcp-Session-Id` viene rilasciato da `initialize`, associato a tale chiave e ha una validità di 24 ore; al massimo 16 sessioni per chiave.
Strumenti	Una per ogni operazione API pubblica visibile alla chiave. Il nome dello strumento corrisponde al comando CLI con `_` al posto di spazi e trattini (`vm firewall add` diventa `vm_firewall_add`) e coincide con il campo `operationId` di OpenAPI. Uno strumento viene elencato solo quando la chiave dispone del relativo ambito e il modulo è abilitato.
Funzionalità	Solo strumenti (nessuna risorsa o prompt).
Dimensione	Corpo della richiesta fino a 1 MB; testo del risultato dello strumento fino a circa 100 KB (il resto viene troncato con una nota); una chiamata richiede al massimo 55 secondi.

Regole di sicurezza

Stesso controllo di REST. Ogni tools/call passa attraverso la pipeline di richieste del pannello: vengono applicati scope, sito, restrizioni IP, rate limit, idempotenza, controlli di proprietà (404 per le risorse di altri) e quote. MCP non può concedere nulla che la chiave non possieda.
Conferma. Gli strumenti che comportano costi, eliminano dati o restituiscono credenziali (ticket per la console, kubeconfig, segreti S3 o SSH, reset delle password, nuove chiavi) richiedono l'argomento confirm: true. La descrizione dello strumento indica all'assistente di passarlo solo dopo l'approvazione dell'utente, in modo che un'istruzione nascosta in una pagina web o in un log non possa attivarla autonomamente.
Idempotenza. Gli strumenti a pagamento accettano idempotency_key; se omesso, viene ricavata una chiave stabile dal nome dello strumento e dagli argomenti, impedendo che un tentativo identico venga addebitato due volte.
Non esposti come strumenti: endpoint di streaming (la chat dell'AI Agent), ticket WebSocket temporanei per SSH o console, download binari e gli endpoint dell'app VPN (/v1/ext/*).
Mai possibile: l'API non consente mai ricariche, modifiche della password, eliminazione dell'account o creazione di chiavi, quindi nessun assistente può eseguirli.

Limiti

Limite	Predefinito
Chiamate agli strumenti per chiave	60 al minuto
Richieste MCP per chiave	240 al minuto
Oltre ai normali limiti di chiave e account	Vedi REST API

Oltre il limite, l'endpoint risponde con HTTP 429, un errore JSON-RPC e Retry-After.

Verifica

Il comando curl sopra restituisce un risultato JSON-RPC con un elenco tools. Vengono visualizzati solo gli strumenti corrispondenti agli scope della chiave.
Nel tuo client chiedi "elenca le mie VM": l'assistente chiama vm_list e mostra il risultato.
Nel portale, il timestamp Last used della chiave viene aggiornato e le chiamate in scrittura compaiono nel Key usage log.

Limiti e note

Accesso tramite browser (OAuth). La pagina di riferimento descrive anche l'accesso tramite browser per i client che supportano MCP OAuth. In un'installazione di NexCMP, il metodo supportato e testato è la chiave API (o cmp login per la CLI).
I siti dei rivenditori non mostrano la sezione MCP; i loro clienti utilizzano il dominio del rivenditore per le API.
Minimo privilegio. Crea una chiave dedicata per ciascun assistente assegnando inizialmente solo gli scope in lettura; aggiungi gli scope in scrittura solo quando necessario.
Revoca la chiave in API keys per interrompere immediatamente l'accesso dell'assistente.

Troubleshooting

Sintomo	Causa	Soluzione
401 con `WWW-Authenticate: Bearer`	Nessuna chiave, chiave errata o token di sessione	Invia `Authorization: Bearer vk_...`.
403 su `Origin`	Una pagina del browser su un'altra origine	Usa un client desktop o CLI oppure chiedi all'amministratore di autorizzare l'origine (`mcp_allowed_origins`).
404 su una richiesta con `Mcp-Session-Id`	La sessione appartiene a un'altra chiave oppure è scaduta	Esegui di nuovo `initialize`.
405 su `GET /mcp`	Previsto: il server non dispone di uno stream di eventi	Usa solo POST (i client lo fanno automaticamente).
L'elenco degli strumenti è breve	Scope della chiave o moduli	Aggiungi gli scope alla chiave; abilita il modulo.
Lo strumento risponde che è necessario `confirm: true`	Strumento a pagamento, di eliminazione o sensibile	L'assistente deve impostare `confirm` dopo la tua approvazione.
429	Rate limit di MCP o della chiave	Attendi `Retry-After`.
Il client non riesce a connettersi con un'intestazione	Client privo di supporto per intestazioni personalizzate	Usa il bridge `mcp-remote`.

Server MCP ​

Descrizione ​

Requisiti ​

Prepara l'infrastruttura ​

Connessione (lato cliente) ​

Come funziona ​

Regole di sicurezza ​

Limiti ​

Verifica ​

Limiti e note ​

Troubleshooting ​