Connettere un client AI (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

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.

Due endpoint MCP

/mcp è l'endpoint cliente (chiavi API cliente, vk_; vedi MCP server). /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

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 (`ak_...`) con i permessi desiderati, oppure l'accesso OAuth per i connettori web (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

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

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.
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.
Copia lo snippet per il tuo client ed eseguilo o incollalo come descritto di seguito.

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

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)

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.

ChatGPT (modalità sviluppatore)

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.

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

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

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

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" }
    }
  }
}

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)

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

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)

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

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.

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.
Apri API & AI agents › Activity: le chiamate vengono elencate con il nome del client e mcp.
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

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). 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

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

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

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

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

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

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

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

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

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 per il formato del file.

Prompt

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`)

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

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.
Il client deve mostrare l'anteprima. Solo dopo l'approvazione viene richiamato lo stesso strumento con gli stessi argomenti più confirm_token.
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.

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

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

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) o i riferimenti secret:// (Configuration as code).
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

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.

Connettere un client AI (MCP) ​

Descrizione ​

Requisiti ​

Prepara l'infrastruttura ​

Collega in NexCMP ​

Claude Code ​

Claude Desktop ​

claude.ai (connettore personalizzato) ​

ChatGPT (modalità sviluppatore) ​

Codex CLI ​

Gemini CLI ​

Cursor ​

OpenAI Agents SDK (Python) ​

OpenAI Responses API ​

Qualsiasi altra cosa (HTTP semplice) ​

Verifica ​

Strumenti ​

Panoramica e log ​

Impostazioni, brand, note legali, moduli ​

Email e avvisi ​

Pagamenti e valuta ​

Infrastruttura e zone ​

Catalogo e piani ​

Clienti e rivenditori ​

Provider IA ​

File di configurazione ​

Prompt ​

Conferma (confirm_token) ​

Come funziona ​

Limiti e note ​

Troubleshooting ​

Connettere un client AI (MCP)

Descrizione

Requisiti

Prepara l'infrastruttura

Collega in NexCMP

Claude Code

Claude Desktop

claude.ai (connettore personalizzato)

ChatGPT (modalità sviluppatore)

Codex CLI

Gemini CLI

Cursor

OpenAI Agents SDK (Python)

OpenAI Responses API

Qualsiasi altra cosa (HTTP semplice)

Verifica

Strumenti

Panoramica e log

Impostazioni, brand, note legali, moduli

Email e avvisi

Pagamenti e valuta

Infrastruttura e zone

Catalogo e piani

Clienti e rivenditori

Provider IA

File di configurazione

Prompt

Conferma (`confirm_token`)

Come funziona

Limiti e note

Troubleshooting