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 se la chiave API dispone dell’ambito di lettura; per gli strumenti di scrittura è necessario l’ambito di scrittura. Utilizzi tools/call per richiamare uno strumento con i relativi argomenti. Le informazioni da conservare tra sessioni possono essere memorizzate con gli strumenti di memoria (remember, recall, forget), mentre le generazioni AI di lunga durata vengono monitorate per ogni chiamata: alleghi un riferimento all’attività in _meta["io.modelcontextprotocol/related-task"] e ProcessMind ne comunica lo stato insieme alla risposta. I metodi di estensione tasks/list, tasks/get e tasks/cancel non sono disponibili.

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 quelli di scrittura richiedono l’ambito write. Il catalogo degli strumenti è documentato nella guida MCP. Si autentichi con x-api-key o Authorization: Bearer <token> (token ottenuto dall’endpoint del token OAuth).

Endpoint: POST /v1/mcp/{tenantId}

Autenticazione: Chiave API associata al Tenant · ambito read · limite di frequenza: 20 richieste/s (picco 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 questo tipo di file

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

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

Autenticazione: Pubblico, senza chiave API · limite di frequenza: 10 richieste/s (picco 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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o campo obbligatorio mancante
• 401 Chiave API mancante, non valida, disabilitata o scaduta

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

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

Autenticazione: Pubblico, senza chiave API · limite di frequenza: 5 richieste/s (picco 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 di 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, espressione di filtro non valida, processo senza modello, tipo di caricamento non supportato o 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 questo tipo di file