Riferimento API: MCP

Il server MCP consente agli assistenti AI di interagire con ProcessMind tramite il Model Context Protocol. Utilizza JSON-RPC 2.0 su Streamable HTTP: invii initialize, quindi tools/list per individuare il catalogo degli strumenti. Gli strumenti di lettura come list_processes vengono elencati solo quando la chiave API dispone dell’ambito read; gli strumenti di scrittura richiedono l’ambito write. Utilizzi tools/call per richiamare uno strumento con i relativi argomenti. I dati condivisi tra sessioni possono essere memorizzati con gli strumenti di memoria (remember, recall, forget), mentre le generazioni AI di lunga durata vengono monitorate per ogni chiamata allo strumento: alleghi un riferimento all’attività in _meta["io.modelcontextprotocol/related-task"] e ProcessMind ne comunica lo stato insieme alla chiamata. I metodi di estensione tasks/list, tasks/get e tasks/cancel non vengono forniti.

Endpoint del server Model Context Protocol (JSON-RPC su Streamable HTTP)

JSON-RPC 2.0 su Streamable HTTP: initialize, tools/list, tools/call, resources/list, resources/read, prompts/list. Gli strumenti di lettura richiedono l’ambito read della chiave, mentre gli strumenti di scrittura richiedono l’ambito write. Il catalogo degli strumenti è documentato nella guida MCP. Esegua l’autenticazione con x-api-key o Authorization: Bearer <token> (token dall’endpoint dei token OAuth).

Endpoint: POST /v1/mcp/{tenantId}

Autenticazione: Chiave API con ambito tenant · ambito read · limite di frequenza 20 richieste/s (burst 40)

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	percorso	Sì	Formato: uuid

Corpo della richiesta:

Richiesta JSON-RPC MCP

{}

Risposta (200):

Risposta JSON-RPC MCP

{
	"message": "string"
}

Campo	Tipo	Obbligatorio	Descrizione
message	string	Sì

Errori:

• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 403 La chiave API non dispone dell’ambito richiesto o dell’accesso all’organizzazione, il tenant è inattivo oppure il piano non consente il tipo di file

Endpoint di autorizzazione OAuth 2.1 (PKCE), reindirizzamenti 302 a redirect_uri con ?code=…

Endpoint: GET /v1/mcp/{tenantId}/oauth/authorize

Autenticazione: Pubblica, senza chiave API · limite di frequenza 10 richieste/s (burst 20)

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	percorso	Sì	Formato: uuid
client_id	string	query	Sì
redirect_uri	string	query	Sì	Formato: uri
code_challenge	string	query	Sì
code_challenge_method	S256	query	No	Valori consentiti: S256
state	string	query	No

Errori:

• 302 Reindirizzamento a redirect_uri con code + state
• 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta

Endpoint dei token OAuth 2.0 (client_credentials o authorization_code + PKCE)

Endpoint: POST /v1/mcp/{tenantId}/oauth/token

Autenticazione: Pubblica, senza chiave API · limite di frequenza 5 richieste/s (burst 10)

Parametri:

Nome	Tipo	Posizione	Obbligatorio	Descrizione
tenantId	string	percorso	Sì	Formato: uuid

Risposta (200):

Token di accesso

{
	"access_token": "string",
	"token_type": "Bearer",
	"expires_in": 0
}

Campo	Tipo	Obbligatorio	Descrizione
access_token	string	Sì	JWT Bearer a breve durata per POST /v1/mcp/{tenantId}
token_type	Bearer	Sì	Valori consentiti: Bearer
expires_in	number	Sì

Errori:

• 400 Richiesta non valida: ad esempio, un’espressione di filtro non valida, un processo senza modello, un tipo di caricamento non supportato o un campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta
• 403 La chiave API non dispone dell’ambito richiesto o dell’accesso all’organizzazione, il tenant è inattivo oppure il piano non consente il tipo di file