Strumenti MCP
Superficie pubblica degli strumenti MCP, OAuth ed esecuzione governata per i client agente.
Panoramica
Numezis espone un server MCP remoto per Claude, ChatGPT e altri client MCP. Gli strumenti corrispondono a operazioni API governate: le letture sono elencate nel manifest dello strumento; le mutazioni rispettano l'attivazione dei moduli, le autorizzazioni e la policy di approvazione per gli strumenti critici.
La configurazione per l'utente finale (connettori, screenshot OAuth) si trova nella guida prodotto MCP. Questa pagina documenta il contratto di integrazione per gli sviluppatori.
Endpoint e trasporto
| Elemento | Valore |
|---|---|
| URL | https://www.numezis.com/mcp |
| Trasporto | Streamable HTTP (JSON-RPC 2.0) |
| Auth | OAuth 2.0 con Dynamic Client Registration |
Invia il contesto di portale tramite la sessione autenticata stabilita al momento
dell'OAuth. L'esecuzione degli strumenti usa le stesse regole AccessMode del
portale aziendale (/c).
Discovery degli strumenti
Dopo l'autorizzazione, chiama tools/list per recuperare i manifest. Ogni
strumento include:
name— identificatore stabile (corrisponde alle superfici strumento del registry)description— riepilogo rivolto all'utenteinputSchema— JSON Schema per gli argomentimanifest.safety—read,writeocriticalmanifest.requiresApproval—trueper le mutazioni critiche
Compaiono solo gli strumenti per i moduli abilitati e le autorizzazioni effettive dell'utente connesso.
Esecuzione e approvazioni
- Il client invia
tools/callcon nome dello strumento e argomenti convalidati. - Il server esegue i controlli di policy (modulo, autorizzazione, stato azienda).
- Gli strumenti critici possono restituire un token di approvazione invece di applicare la mutazione.
- L'utente conferma nell'interfaccia Numezis; il client riprova con il riferimento di approvazione.
Non aggirare i passaggi di approvazione nell'automazione: usa strumenti di lettura non critici per il preflight dei dati, poi mostra all'utente l'UX di approvazione.
Errori
Gli errori MCP rispecchiano la semantica dell'API: errori di autorizzazione, errori di convalida e limiti di frequenza sono restituiti come errori RPC strutturati. Registra gli id di correlazione delle risposte quando apri ticket di supporto.