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.
tools/list pubblica facciate di dominio chiamabili. Una facciata esegue
un'operazione API governata: una lettura resta una lettura, e una mutazione
segue sempre l'attivazione dei moduli, le autorizzazioni e la policy di
approvazione.
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. L'elenco è paginato (nextCursor).
Ogni voce è una facciata chiamabile, nominata numezis.<dominio>.<verbo> oppure
numezis.<dominio>.<famiglia>.<verbo>. L'elenco non contiene
numezis.load_domains, né un alias ritirato, né un dispatcher generico come
sales.query. Una seconda chiamata restituisce gli stessi nomi.
Ogni strumento include:
name— la facciata da passare atools/calldescription— la frase di consenso mostrata prima che l'host chieda confermainputSchema— JSON Schema; una facciata di famiglia prenderesourceeargsannotations.title— titolo localizzato (Dominio · Famiglia · Verbo)annotations.readOnlyHinteannotations.destructiveHint— la chiamata legge soltanto, oppure può modificare dei record
Compaiono solo le facciate per i moduli abilitati e le autorizzazioni
effettive dell'utente connesso. _meta.toolAdmission vale
domain_facade_catalog.
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.