---
title: Connettere un client AI (MCP)
description: Collega Claude Code, Codex CLI, Gemini CLI, Cursor, Claude Desktop, claude.ai, ChatGPT o SDK OpenAI all'endpoint MCP admin del pannello con tutti i tool.
url: https://nexcmp.com/it/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Connettere un client AI (MCP) {#connect-an-ai-client-mcp}

> **Dove nel pannello admin:** System › Settings › API & AI agents (`/agent/keys`), la scheda **Connect an AI** mostra l'URL dell'endpoint e uno snippet pronto da copiare per ogni client, compilato con la chiave appena creata.

## Descrizione {#what-it-does}

Il protocollo **Model Context Protocol (MCP)** consente a un client AI di richiamare strumenti. Il tuo pannello ospita un server MCP admin su `https://cloud.example.com/mcp/admin`. Collega il tuo strumento AI e chiedi in linguaggio naturale: "cosa resta da configurare?", "aggiungi il mio cluster Proxmox", "crea piani con un margine del 40%". Il client richiama gli strumenti di amministrazione sottostanti; il pannello verifica i permessi, ti chiede conferma prima di qualsiasi operazione rischiosa e registra ogni chiamata.

::: info Due endpoint MCP
`/mcp` è l'endpoint **cliente** (chiavi API cliente, `vk_`; vedi [MCP server](https://nexcmp.com/it/docs/developers/mcp/)). `/mcp/admin` è l'endpoint **admin** descritto qui (chiavi admin `ak_` o OAuth). I due non si mescolano mai: gli strumenti admin non sono visibili su `/mcp` e `/mcp/admin` accetta solo chiavi admin.
:::

## Requisiti {#requirements}

| Elemento | Requisito |
|---|---|
| Endpoint | `https://cloud.example.com/mcp/admin` sul dominio del tuo pannello. Copia l'URL esatto dalla scheda **Connect an AI**. La stessa pagina elenca un URL locale (`http://127.0.0.1:<port>/mcp/admin`) per gli strumenti in esecuzione sul server stesso. |
| Credenziali | Una [admin API key](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/) (`ak_...`) con i permessi desiderati, **oppure** l'accesso OAuth per i connettori web ([OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/)). |
| Client | Qualsiasi client MCP che supporta il trasporto **Streamable HTTP** e un'intestazione `Authorization` personalizzata. Versioni del protocollo 2025-11-25, 2025-06-18 e 2025-03-26. |
| Rete | Se inserisci un tuo reverse proxy davanti al pannello, questo deve inoltrare `/mcp/admin`. I connettori web (claude.ai, ChatGPT) si collegano dai server del fornitore, quindi l'URL deve essere raggiungibile da internet. |

## Prepara l'infrastruttura {#prepare-the-infrastructure}

Nessuna installazione richiesta sul server. Se limiti la chiave per IP, assicurati che l'indirizzo da cui si collega il client rientri nell'intervallo. Testa prima la raggiungibilità:

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

Una risposta pari a `401` con un'intestazione `WWW-Authenticate: Bearer ... resource_metadata=...` indica che l'endpoint è attivo e richiede le credenziali.

## Collega in NexCMP {#connect-in-nexcmp}

1. Crea una chiave: **System › Settings › API & AI agents › API keys › New key**. Per un primo test usa solo `admin:read`; aggiungi i permessi di scrittura quando ti servono. Vedi [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/).
2. Apri la scheda **Connect an AI**. Finché la finestra di dialogo "chiave creata" è ancora aperta, ogni snippet sottostante contiene già la tua chiave reale. In caso contrario, mostra il placeholder `ak_YOUR_KEY`.
3. Copia lo snippet per il tuo client ed eseguilo o incollalo come descritto di seguito.

![Scheda Connect an AI con l'URL MCP e una scheda con il pulsante di copia per ciascun client](https://nexcmp.com/it/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

```bash
claude mcp add --transport http nexcmp https://cloud.example.com/mcp/admin \
  --header "Authorization: Bearer ak_XXXX"
```

Quindi avvia `claude` e chiedi "list the tools from nexcmp" o "what is left to set up?".

Verificato il 30/10/2026 con Claude Code 2.1: `claude mcp add --transport http …` scrive sul server (aggiungi `-s project` per conservarlo nel file `.mcp.json` del progetto — Claude Code chiede di approvare i server di progetto la prima volta). Per gli script, `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` viene eseguito senza la richiesta di approvazione e consente a Claude di utilizzare solo gli strumenti del pannello.

### Claude Desktop {#claude-desktop}

Richiede Node.js 18 o versioni successive. Aggiungi questo a `claude_desktop_config.json` (utilizza il bridge `mcp-remote`) e riavvia Claude Desktop:

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

Se il tuo sistema altera lo spazio nell'argomento dell'intestazione, inserisci l'intero valore in una variabile d'ambiente, esattamente come per l'endpoint cliente: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` con `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (connettore personalizzato) {#claude-ai-custom-connector}

Nessuna chiave necessaria: effettua l'accesso con OAuth. In claude.ai apri le impostazioni dei connettori, aggiungi un connettore personalizzato, incolla `https://cloud.example.com/mcp/admin`, accedi con il tuo account admin di NexCMP e seleziona le autorizzazioni nella schermata di consenso. Dettagli: [OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (modalità sviluppatore) {#chatgpt-developer-mode}

Nessuna chiave necessaria. In ChatGPT attiva la modalità sviluppatore, aggiungi un connettore MCP con l'URL `https://cloud.example.com/mcp/admin`, seleziona OAuth e accedi con il tuo account admin di NexCMP. Dettagli: [OAuth connectors](https://nexcmp.com/it/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Aggiungi a `~/.codex/config.toml`:

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

Quindi esporta la chiave nella shell che avvia Codex:

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip Non interattivo `codex exec`
In `codex exec` (script, CI) Codex non chiede conferma prima di chiamare gli strumenti e salta quelli che modificano i dati. Aggiungi `default_tools_approval_mode = "approve"` sotto `[mcp_servers.nexcmp]` per consentirne la chiamata; il pannello restituisce comunque un'anteprima e chiede conferma per le azioni relative a denaro, sicurezza ed eliminazione. Verificato con Codex CLI 0.166 il 30/10/2026.
:::

### Gemini CLI {#gemini-cli}

Aggiungi a `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

Gemini CLI disattiva i server MCP nelle cartelle che non considera attendibili. Avvialo in una cartella di cui ti fidi (o considerala attendibile quando richiesto), quindi verifica con `gemini mcp list`: viene mostrato `nexcmp … Connected`. Puoi tenere la chiave fuori dal file usando `"Authorization": "Bearer $NEXCMP_KEY"`. Verificato con Gemini CLI 0.66 il 30/10/2026.

### Cursor {#cursor}

Aggiungi a `~/.cursor/mcp.json` (o a `.cursor/mcp.json` in un progetto):

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip Mantieni la chiave fuori dai file di configurazione
Dove il client lo supporta, leggi la chiave da una variabile d'ambiente anziché scriverla nel file: Codex lo fa per impostazione predefinita (`bearer_token_env_var`) e Cursor accetta `"Bearer ${env:NEXCMP_KEY}"`. Non effettuare mai il commit di un file che contiene una chiave.
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

Un'esecuzione completa (verificata con `openai-agents` 0.24 il 30/10/2026 — uno strumento di lettura, seguito da una modifica del saldo che ha restituito l'anteprima di conferma ed è stata applicata alla seconda chiamata con `confirm_token`):

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

Passa il server come strumento di tipo `mcp`. Tieni `require_approval` su `always` affinché il programma chieda conferma prima di ogni chiamata:

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### Qualsiasi altra cosa (HTTP semplice) {#anything-else-plain-http}

Un client senza MCP può chiamare gli stessi strumenti tramite HTTP. `GET /v1/admin/agent/tools` li elenca, `POST /v1/admin/agent/tools/<name>` ne esegue uno con un corpo JSON di argomenti e `GET /v1/admin/openapi.json` restituisce una descrizione OpenAPI 3.1 (ciascun strumento corrisponde a un'operazione). Tutti richiedono `Authorization: Bearer ak_...`.

## Verifica {#verify}

1. Senza un client, elenca gli strumenti:

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

   La risposta è un risultato JSON-RPC con gli strumenti consentiti dai tuoi ambiti.
2. Nel client chiedi "run system_health". Restituisce gli avvisi, lo stato di salute dell'infrastruttura connessa, i pagamenti, l'email, l'IA e lo stato della licenza.
3. Apri **API & AI agents › Activity**: le chiamate vengono elencate con il nome del client e `mcp`.
4. Sul server, `sudo nexcmp status` stampa la riga "MCP admin" che indica `ready` quando l'endpoint risponde (lo stato HTTP 401 senza chiave indica il corretto funzionamento).

## Strumenti {#tools}

Il server offre 58 strumenti. Un client vede solo quelli consentiti dagli ambiti della sua chiave: gli strumenti di lettura richiedono `admin:read`, quelli di scrittura necessitano del proprio ambito. Gli strumenti di scrittura accettano anche un argomento facoltativo `confirm_token` (vedi [Confirmation](#confirmation-confirm-token)). Gli argomenti vengono verificati rispetto allo schema di ogni strumento: quelli sconosciuti o digitati in modo errato vengono rifiutati con un messaggio che ne specifica il nome.

I prezzi sono in USD: i prezzi dei piani in dollari all'ora (`hourly_usd`), i saldi in centesimi. I segreti possono essere impostati ma non vengono mai restituiti.

### Panoramica e log {#overview-and-logs}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `system_health` | Avvisi che richiedono attenzione, salute dell'infrastruttura, pagamenti, email, IA, licenza e stato degli aggiornamenti. | `admin:read` | No | No |
| `setup_checklist` | Cosa è configurato e cosa manca: licenza, infrastruttura, zona, template OS, piani, pagamenti, email, brand, note legali, ordine di test. | `admin:read` | No | No |
| `license_status` | Stato della licenza e presenza di una versione di NexCMP più recente. | `admin:read` | No | No |
| `audit_search` | Cerca nel registro di audit amministrativo e nel registro delle chiavi API. | `admin:read` | No | No |

### Impostazioni, brand, note legali, moduli {#settings-branding-legal-modules}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `settings_get` | Leggi le impostazioni generali (filtri `keys`; un finale in `*` corrisponde a un prefisso). | `admin:read` | No | No |
| `settings_update` | Modifica le impostazioni generali da un oggetto `values` flat. Sono accettate solo le chiavi elencate da `settings_get`. | `settings:write` | Sì | Quando una chiave influisce su pagamenti, sicurezza di accesso, interruttori globali o prezzi |
| `branding_get` | Nome del brand, colore, valuta di visualizzazione, nome del venditore, URL del logo e della favicon. | `admin:read` | No | No |
| `branding_update` | Imposta il nome del brand (fino a 60 caratteri), il colore (`#rrggbb`), la valuta di visualizzazione (`usd` o `vnd`) e il nome del venditore. | `settings:write` | Sì | No |
| `branding_logo_set` | Carica un logo chiaro o scuro o una favicon da un URL https o base64 (PNG, JPEG, WEBP, ICO o SVG, fino a 512 KB). | `settings:write` | Sì | No |
| `legal_get` | Termini di servizio e informativa sulla privacy (inglese e vietnamite) e i valori predefiniti neutrali. | `admin:read` | No | No |
| `legal_update` | Imposta i testi dei termini e della privacy (markdown semplice, niente HTML, fino a 50 KB ciascuno). Una stringa vuota ripristina il valore predefinito. | `settings:write` | Sì | No |
| `modules_get` | Quali moduli facoltativi sono attivi e quali possono essere attivati. | `admin:read` | No | No |
| `module_set` | Attiva o disattiva un modulo facoltativo (`key` deve essere uno tra `settable`). | `settings:write` | Sì | No |

### Email e avvisi {#email-and-alerts}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `smtp_get` | Impostazioni email in uscita (password mascherata) e stato della coda. | `admin:read` | No | No |
| `smtp_configure` | Imposta il server SMTP. La modifica di host, porta o sicurezza richiede nuovamente la password. | `settings:write` (+ `secrets:write` per la password) | Sì | No |
| `smtp_test` | Invia una vera email di test con le impostazioni salvate. | `settings:write` | Invia un'email | No |
| `telegram_get` | Canali di notifica amministrativi (id chat; i token dei bot non vengono mai restituiti). | `admin:read` | No | No |
| `telegram_configure` | Aggiungi o aggiorna il canale di avviso Telegram (token del bot e id chat) e attiva o disattiva gli avvisi amministrativi. | `settings:write` (+ `secrets:write` per il token) | Sì | No |
| `telegram_test` | Invia un messaggio di test al canale Telegram. | `settings:write` | Invia un messaggio | No |

### Pagamenti e valuta {#payments-and-currency}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `payments_get` | Stato di Stripe, PayPal, criptovalute (USDT) e bonifico bancario, oltre a canali abilitati e commissioni. | `admin:read` | No | No |
| `payment_configure` | Imposta le credenziali di un gateway (`stripe`, `paypal`, `crypto` o `bank`). | `billing:write` (+ `secrets:write`) | Sì | Sempre |
| `payment_test` | Verifica le credenziali salvate di un gateway presso il provider. | `billing:write` | No | No |
| `currency_get` | Valuta di visualizzazione e tasso da USD a VND (automatico o manuale). | `admin:read` | No | No |
| `currency_set` | Imposta la valuta di visualizzazione e/o un tasso manuale (0 significa automatico, altrimenti da 15000 a 50000). | `billing:write` | Sì | Quando modifichi il tasso manuale |

### Infrastruttura e zone {#infrastructure-and-zones}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `cloudstack_get` | Endpoint CloudStack salvato e ID di zona e rete (chiavi mascherate). | `admin:read` | No | No |
| `cloudstack_test` | Testa un endpoint con chiave API e segreto senza salvare; elenca le zone. | `infra:write` (+ `secrets:write`, poiché passi le chiavi) | No | No |
| `cloudstack_connect` | Salva la connessione CloudStack. | `infra:write` (+ `secrets:write`) | Sì | Sempre |
| `proxmox_list` | Cluster Proxmox VE aggiunti come sorgenti, con relativo stato di salute. | `admin:read` | No | No |
| `proxmox_add` | Aggiungi un cluster Proxmox VE con un token API (`user@realm!tokenid`) e il relativo segreto. | `infra:write` (+ `secrets:write`) | Sì | No |
| `proxmox_test` | Connettiti a un cluster tramite ID; il primo successo memorizza il suo certificato TLS. | `infra:write` | Sì | No |
| `proxmox_attach_zone` | Vendi un cluster Proxmox in una zona esistente, opzionalmente con un nodo come regione. | `infra:write` | Sì | No |
| `zones_list` | Zone (posizioni) che i clienti possono scegliere. | `admin:read` | No | No |
| `zone_create` | Crea una zona. | `infra:write` | Sì | No |

### Catalogo e piani {#catalog-and-plans}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `templates_list` | Template OS che i clienti possono installare. | `admin:read` | No | No |
| `templates_sync` | Importa template OS da CloudStack. | `catalog:write` | Sì | No |
| `template_update` | Abilita o nascondi un template, rinominalo, imposta l'utente di login o l'ordine. | `catalog:write` | Sì | No |
| `offerings_list` | Offerte di servizio CloudStack (CPU, memoria, disco di root) su cui basare i piani. | `admin:read` | No | No |
| `plans_list` | Piani con prezzo orario e mensile, dimensioni, zona e numero di server che li utilizzano. | `admin:read` | No | No |
| `plan_create` | Crea un piano. Prezzo come `hourly_usd`. I piani CloudStack richiedono `cs_offering_id`; i piani Proxmox richiedono `backend_id`. | `catalog:write` | Sì | No |
| `plan_update` | Rinomina, mostra o nascondi, abilita o disabilita o modifica il prezzo di un piano. Le modifiche alle dimensioni di un piano in uso richiedono una copia. | `catalog:write` | Sì | Quando il prezzo cambia |
| `plans_from_offerings` | Crea una tabella di piani iniziali dalle offerte (o dimensioni di Proxmox) usando i costi e una percentuale di margine. Restituisce un'anteprima; richiama con `apply=true` per creare i piani. | `catalog:write` | Con `apply=true` | Sempre attivo all'applicazione |
| `quota_defaults_get` | Limiti predefiniti dei clienti. | `admin:read` | No | No |
| `quota_defaults_set` | Modifica le impostazioni di `quota_*`. | `catalog:write` | Sì | No |
| `coupons_list` | Lotti di codici sconto e regalo. | `admin:read` | No | No |
| `coupon_create` | Crea un lotto di codici: tipo `money` (valore nominale in centesimi di USD) o `percent` (da 1 a 100, con uno sconto massimo). | `catalog:write` | Sì | Sempre |

### Clienti e rivenditori {#customers-and-resellers}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `customers_search` | Trova clienti tramite e-mail, nome o IP. | `admin:read` | No | No |
| `customer_get` | Account, saldo, server e fatturazione recente di un cliente. | `admin:read` | No | No |
| `customer_adjust_balance` | Aggiunge (positivo) o rimuove (negativo) credito in centesimi di USD. È richiesto un motivo. | `billing:write` | Sì | Sempre |
| `customer_block` | Blocca un cliente, interrompendo facoltativamente i suoi server. È richiesto un motivo. | `customers:write` | Sì | Sempre |
| `customer_unblock` | Sblocca un cliente. | `customers:write` | Sì | No |
| `resellers_list` | Rivenditori con portafoglio e stato. | `admin:read` | No | No |
| `reseller_get` | Sito, portafoglio, utenti e gateway di un rivenditore. | `admin:read` | No | No |

### Provider IA {#ai-provider}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `ai_provider_get` | Il provider compatibile con OpenAI utilizzato dall'AI Chat e dall'AI Agent del cliente (chiave mascherata). | `admin:read` | No | No |
| `ai_provider_set` | Imposta il provider: URL di base, modello, chiave API, modelli di fallback, livello di ragionamento, abilitato. | `ai:write` (+ `secrets:write` per la chiave) | Sì | No |
| `ai_provider_test` | Pone una domanda al provider salvato per verificarne il corretto funzionamento. | `ai:write` | No | No |

### File di configurazione {#configuration-files}

| Strumento | Descrizione | Ambito | Modifica dati | Chiede conferma |
|---|---|---|---|---|
| `config_export` | Esporta la configurazione come YAML (i segreti diventano riferimenti `secret://`). | `admin:read` | No | No |
| `config_plan` | Confronta una configurazione YAML con il pannello attivo ed elenca ciò che cambierebbe. | `admin:read` | No | No |
| `config_apply` | Applica una configurazione YAML sezione per sezione. Ogni modifica segue le normali regole di ambito e conferma. | `admin:read` + l'ambito di ogni modifica | Sì | Per ogni modifica |

Vedi [Configuration as code](https://nexcmp.com/it/docs/configure-with-ai/config-as-code/) per il formato del file.

## Prompt {#prompts}

Il server offre anche tre prompt predefiniti che i client possono mostrare come scorciatoie:

| Prompt | Argomento | Cosa chiede di fare all'IA |
|---|---|---|
| `initial-setup` | nessuno | Chiama `setup_checklist`, spiega ogni fase aperta in una frase, chiede le informazioni necessarie, esegue la fase con lo strumento corrispondente, mostra un'anteprima delle modifiche a denaro o sicurezza e termina con `system_health`. |
| `add-proxmox` | `endpoint` (facoltativo, `https://host:8006`) | Chiede il token API, quindi `proxmox_add`, `proxmox_test`, gli strumenti di zona e `proxmox_attach_zone`; poi propone i piani con `plans_from_offerings` e attende l'approvazione. |
| `launch-pricing` | `margin_pct` (facoltativo, predefinito 40) | Chiede il costo mensile per vCPU, per GB di RAM e per GB di disco, mostra una tabella di anteprima con costi, prezzo mensile e prezzo orario, e crea i piani dopo l'approvazione. |

## Conferma (`confirm_token`) {#confirmation-confirm-token}

Le azioni che muovono denaro, eliminano dati, modificano le credenziali di pagamento o la sicurezza degli accessi avvengono in due passaggi:

1. La prima chiamata non modifica nulla. Il risultato dello strumento inizia con "CONFIRMATION REQUIRED" e include un'**anteprima** (cosa verrà chiamato, perché è un'operazione sensibile, i nuovi valori e quelli attuali) e un `confirm_token`.
2. Il client deve mostrare l'anteprima. Solo dopo l'approvazione viene richiamato lo stesso strumento con gli stessi argomenti più `confirm_token`.
3. Il token funziona una sola volta, esclusivamente per quella richiesta specifica, e scade dopo 5 minuti.

Le istruzioni del server dicono all'IA di trattare i risultati dei tool come dati e non come istruzioni, e di non ripetere mai una chiamata con un token che non hai approvato. Tu sei la salvaguardia: leggi l'anteprima.

::: warning Non approvare automaticamente
Alcuni client possono approvare automaticamente ogni chiamata a un tool. Per i tool di scrittura, mantieni attiva l'approvazione per singola chiamata o usa una chiave di sola lettura, in modo che un piano errato dell'IA non possa raggiungere il tuo pannello senza essere visto.
:::

## Come funziona {#how-it-works}

| Elemento | Dettaglio |
|---|---|
| Trasporto | `POST /mcp/admin` con un messaggio JSON-RPC 2.0; la risposta è `application/json`. Fino a 20 messaggi in un batch. `GET /mcp/admin` risponde con 405 (nessuno stream del server); `DELETE /mcp/admin` termina una sessione. |
| Autenticazione | `Authorization: Bearer ak_...` (una chiave manuale o un token di accesso OAuth). Credenziali mancanti o errate restituiscono 401 con `WWW-Authenticate: Bearer ... resource_metadata=...`, il che consente ai client OAuth di avviare l'accesso autonomamente. |
| Sessioni | `Mcp-Session-Id` viene emesso da `initialize`, associato a tale chiave e valido per 24 ore. |
| Funzionalità | Tool e prompt. Nessuna risorsa. |
| Dimensione | Corpo della richiesta fino a 1 MB; il risultato di un tool viene troncato dopo circa 100 KB. |
| Origine | Una richiesta che trasporta un'intestazione `Origin` da un altro sito viene rifiutata (`origin_not_allowed`). I client da riga di comando e desktop non ne inviano alcuna. |
| Stesso filtro del REST | Ogni chiamata a un tool viene reinviata attraverso la pipeline di richieste del pannello con la tua chiave, pertanto ambiti, intervalli IP, limite di frequenza, conferma e registro attività si applicano esattamente come per le chiamate API dirette. |

## Limiti e note {#limits-notes}

- Un tool che non riesci a vedere è un ambito che non hai concesso. Aggiungi l'ambito a una nuova chiave.
- Impostare una password o una chiave API tramite un client IA significa che il segreto passa attraverso quell'IA. Se preferisci, lascia disattivato `secrets:write` e inserisci tu stesso i segreti nell'amministrazione, oppure usa il campo **Secret** di AI Chat ([AI Chat in the admin](https://nexcmp.com/it/docs/configure-with-ai/ai-chat-in-admin/#secrets)) o i riferimenti `secret://` ([Configuration as code](https://nexcmp.com/it/docs/configure-with-ai/config-as-code/#secrets)).
- I client non condividono le sessioni: ogni connessione inizia con `initialize`.
- Revoca la chiave in **API & AI agents** per isolare immediatamente un client IA.

## Troubleshooting {#troubleshooting}

| Sintomo | Causa | Soluzione |
|---|---|---|
| 401 `invalid_key` | Chiave errata, troncata o non amministrativa (ad esempio una chiave `vk_`) | Usa una chiave `ak_`. |
| 401 `key_expired` o `key_revoked` | La chiave è scaduta o è stata revocata | Crea una nuova chiave. |
| 403 `ip_not_allowed` | Il tuo indirizzo IP è al di fuori degli intervalli IP della chiave | Connettiti da un IP consentito. |
| 403 `origin_not_allowed` | Una pagina del browser su un'altra origine ha chiamato l'endpoint | Usa un client desktop o CLI. |
| 404 su una richiesta con `Mcp-Session-Id` | La sessione appartiene a un'altra chiave oppure è scaduta | Invia di nuovo `initialize`. |
| 400 unsupported `MCP-Protocol-Version` | Il client utilizza una versione che il server non riconosce | Aggiorna il client; supportate: 2025-11-25, 2025-06-18, 2025-03-26. |
| L'elenco degli strumenti è breve | Ambiti della chiave | Crea una chiave con più ambiti. |
| `insufficient_scope` su una chiamata | Un tool richiede un secondo ambito, ad esempio `secrets:write` | Aggiungi l'ambito a una nuova chiave. |
| 429 `rate_limited` | Più chiamate al minuto di quelle consentite dalla chiave | Attendi `Retry-After` o aumenta il limite su una nuova chiave. |
| claude.ai o ChatGPT non riescono a connettersi | L'URL non è raggiungibile da internet o un proxy blocca `/mcp/admin` o `/oauth-admin/` | Verifica DNS, TLS e reverse proxy. |

Per tutti i codici di errore, vedi [Admin API keys](https://nexcmp.com/it/docs/configure-with-ai/admin-api-keys/#errors).