---
title: Server MCP
description: Collega assistenti AI (Claude, Cursor, VS Code) all'API con l'endpoint MCP /mcp: autenticazione, configurazione client, strumenti e regole di sicurezza.
url: https://nexcmp.com/it/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Server MCP {#mcp-server}

> **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 {#what-it-does}

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.

::: tip 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](https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/) (endpoint `/mcp/admin`, chiavi admin `ak_`).
:::

## Requisiti {#requirements}

| 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](https://nexcmp.com/it/docs/developers/api-keys/) (`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 {#prepare-the-infrastructure}

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) {#connect-customer-side}

1. 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.
2. 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.

3. 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 {#how-it-works}

| 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 {#safety-rules}

- **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 {#limits}

| 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](https://nexcmp.com/it/docs/developers/api/#rate-limits) |

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

## Verifica {#verify}

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

## Limiti e note {#limits-notes}

- **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 {#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`. |