Planfix MCP

MCP (Model Context Protocol) consente agli assistenti AI e ad altre applicazioni compatibili di lavorare con i dati di Planfix tramite un protocollo standard.

Dopo aver stabilito una connessione, il client riceve solo le funzionalità autorizzate esplicitamente e opera per conto del dipendente che ha effettuato l’accesso. Restano valide le autorizzazioni standard di accesso a Planfix: un assistente AI non può visualizzare o modificare elementi a cui l’utente non ha accesso.

Le azioni disponibili dipendono dal client MCP, dalle autorizzazioni concesse e dalla versione corrente del server. Ad esempio, se vengono concesse le autorizzazioni corrispondenti, un client può essere in grado di trovare compiti e contatti, leggerne i dettagli e aggiungere commenti.

Requisiti

un account Planfix per dipendenti;
un client MCP che supporti Streamable HTTP e OAuth.

Indirizzo del server MCP

Usa questo URL del server MCP:

https://mcp.planfix.com/mcp

L’URL è lo stesso per tutti gli account Planfix. Non aggiungere il nome dell’account né inviare un’intestazione separata per l’account. L’account viene selezionato durante l’autorizzazione OAuth.

Connessione di qualsiasi client MCP

Apri le impostazioni del server MCP nel client.
Aggiungi un nuovo server usando il trasporto Streamable HTTP.
Inserisci un nome, ad esempio Planfix, e l’URL MCP.
Salva le impostazioni e avvia l’autenticazione OAuth.
Nella finestra del browser che si apre, seleziona il tuo account Planfix. Puoi trovarlo per nome, URL o indirizzo email.
Controlla il nome dell’applicazione e le autorizzazioni richieste, quindi conferma la connessione.

Se l’applicazione non è ancora stata autorizzata nell’account, Planfix indicherà che è necessaria l’approvazione di un amministratore. Un amministratore dell’account o un amministratore tecnico può approvare l’applicazione. Se la persona che la connette è anche l’amministratore, può approvarla e connetterla in un’unica operazione.

Per una connessione DCR di Codex, la richiesta non può essere inoltrata a un amministratore dopo l’avvio dell’accesso. Scegli quindi in anticipo lo scenario appropriato nella sezione successiva.
Per Codex, l’approvazione è necessaria solo la prima volta che un’applicazione CIMD si connette all’account. Deve essere effettuata da un amministratore. In seguito, i dipendenti possono connettersi autonomamente.

Connessione di Codex

Scegli l’opzione in base al fatto che tu sia o meno un amministratore dell’account a cui vuoi connetterti.

Consigliato: connessione tramite CIMD

Su planfix.com, Codex seleziona automaticamente CIMD. Un amministratore approva una volta l’applicazione CIMD nell’account; in seguito, i dipendenti possono completare l’accesso OAuth senza un’altra approvazione dell’applicazione. Per questo metodo non è necessario creare manualmente un’applicazione, fornire un client_id, aggiungere un URI di reindirizzamento o salvare un client secret.

Per la prima connessione, un amministratore dell’account o un amministratore tecnico esegue:

codex mcp add planfix --url https://mcp.planfix.com/mcp
codex mcp login planfix

Codex apre un browser. Seleziona un account Planfix di cui sei amministratore, controlla le autorizzazioni richieste e seleziona Approva e connetti. L’applicazione CIMD richiede questa approvazione una sola volta per account.

In seguito, ogni dipendente che necessita di accesso esegue gli stessi comandi:

codex mcp add planfix --url https://mcp.planfix.com/mcp
codex mcp login planfix

Il dipendente accede con il proprio account Planfix e conferma il proprio accesso. L’amministratore non deve approvare di nuovo l’applicazione CIMD.

Alternativa: usare un’applicazione di proprietà dell’account

Usa questo metodo se ti serve un client OAuth predefinito, gestito dall’account e con un client_id permanente, oppure se CIMD non può essere usato nella tua configurazione.

Un amministratore dell’account o un amministratore tecnico crea l’applicazione:

Apri Gestione account → API → Applicazioni OAuth e MCP.
In Applicazioni di proprietà di questo account, seleziona Crea applicazione.
Inserisci un nome, ad esempio Codex.
Seleziona Client pubblico. Codex non necessita di un client secret.
Aggiungi http://127.0.0.1/callback come URI di reindirizzamento.
Seleziona le autorizzazioni minime necessarie e salva l’applicazione.
Comunica il client_id generato ai dipendenti che effettueranno la connessione.

Planfix pubblica un issuer e supporta risposte di autorizzazione associate all’issuer; pertanto, un client Codex preregistrato appena aggiunto usa il callback stabile http://127.0.0.1/callback. Durante l’accesso, Codex inserisce una porta loopback temporanea e Planfix accetta tale porta se l’host e il percorso restano invariati.

Ogni utente aggiunge il server usando l’ID fornito e accede:

codex mcp add planfix --url https://mcp.planfix.com/mcp --oauth-client-id CLIENT_ID
codex mcp login planfix

Codex mostra l’URL di callback completo. Con la configurazione standard è:

OAuth callback URL: http://127.0.0.1/callback

Se Codex mostra un indirizzo diverso a causa di un’impostazione personalizzata del callback, chiedi all’amministratore di aggiungere all’applicazione esattamente quell’URI di reindirizzamento.

Fornire --oauth-client-id indica a Codex di usare il client preregistrato e di ignorare CIMD e DCR. La configurazione salvata è simile a questa:

[mcp_servers.planfix]
url = "https://mcp.planfix.com/mcp"

[mcp_servers.planfix.oauth]
client_id = "CLIENT_ID"
callback_url = "http://127.0.0.1/callback"

Quando avvii l’accesso, Planfix apre l’account proprietario dell’applicazione. Controlla le autorizzazioni e conferma la connessione.

App Codex ed estensione per IDE

L’app Codex, Codex CLI e l’estensione per IDE condividono la configurazione MCP sullo stesso computer. Dopo la configurazione iniziale tramite CLI, riavvia l’app o l’estensione. Il server comparirà in Impostazioni → Server MCP. Se viene visualizzato Autentica, selezionalo e completa l’accesso.

Inserisci /mcp nel compositore di Codex per visualizzare i server MCP attivi.

Per visualizzare i server configurati e il relativo stato dalla CLI, esegui:

codex mcp list

I controlli e i comandi attuali di Codex, nonché le regole per la selezione del callback, sono descritti nella documentazione ufficiale di OpenAI su MCP.

Più account in Codex

Ogni connessione è associata a un account e a un utente.

Con CIMD, un amministratore deve approvare l’applicazione una volta per ciascun account a cui vuoi connetterti. Aggiungi ogni connessione con un nome diverso e seleziona l’account desiderato durante l’accesso OAuth. Se usi invece applicazioni di proprietà dell’account, ogni account deve avere la propria applicazione e il proprio client_id.

Non modificare l’URL MCP e non aggiungere il nome dell’account alle richieste. Il server determina l’account dal token OAuth.

Risoluzione dei problemi di connessione di Codex

Se durante il primo accesso CIMD è richiesta l’approvazione dell’amministratore, completa la connessione come amministratore dell’account o amministratore tecnico e seleziona Approva e connetti. Dopo l’approvazione dell’applicazione, i dipendenti possono accedere autonomamente.

Se CIMD non può essere usato e Codex richiede un client_id, usa il metodo alternativo descritto sopra, basato su un’applicazione di proprietà dell’account.

Altri client MCP senza registrazione automatica

I client MCP moderni possono registrarsi automaticamente tramite CIMD o DCR. La registrazione automatica non concede di per sé l’accesso all’account: continuano ad applicarsi i criteri dell’account e l’approvazione dell’amministratore.

Se un altro client richiede un client_id predefinito, chiedi a un amministratore di creare un’applicazione pubblica di proprietà dell’account:

Apri Gestione account → API → Applicazioni OAuth e MCP.
In Applicazioni di proprietà di questo account, crea un’applicazione.
Seleziona Client pubblico.
Aggiungi l’URI di reindirizzamento mostrato dal client MCP.
Seleziona le autorizzazioni minime necessarie.
Fornisci il client_id generato all’utente oppure aggiungilo alle impostazioni del client.

L’applicazione può connettersi solo all’account che l’ha creata. Per i dettagli, vedi Applicazioni OAuth e MCP in un account.

Disconnessione di MCP

Per revocare la connessione:

Apri la scheda utente in Planfix.
Vai a Gestione sessioni.
Individua l’applicazione contrassegnata con MCP ed elimina la sessione.
Rimuovi o disattiva il server nel client MCP se non ti serve più.

L’eliminazione della sessione revoca i token OAuth associati. Per connettersi di nuovo, sarà necessario effettuare un nuovo accesso e dare il consenso.

Un amministratore può revocare l’accesso dell’applicazione per l’intero account in Gestione account → API → Applicazioni OAuth e MCP.

Sicurezza

Connetti solo applicazioni di cui ti fidi.
Prima di approvare, verifica il nome dell’applicazione, il proprietario, l’URI di reindirizzamento e le autorizzazioni richieste.
Concedi le autorizzazioni minime necessarie. Non concedere autorizzazioni di modifica o eliminazione per un caso d’uso di sola lettura.
Non incollare mai un token di accesso o un token di aggiornamento in una chat, nelle impostazioni delle richieste o nei log.
Ricorda che i contenuti di compiti, contatti e commenti potrebbero essere inviati a un servizio AI esterno, in base ai termini di trattamento dei dati di tale servizio.
Rimuovi la connessione da Gestione sessioni se non viene più usata o se non la riconosci.

Risoluzione dei problemi

Se per l’accesso DCR è necessaria l’approvazione dell’amministratore, accedi come amministratore dell’account o amministratore tecnico e fai clic su Consenti e connetti. Un normale dipendente non può inoltrare una richiesta DCR già avviata per ottenere un’approvazione separata.
Se per il primo accesso CIMD è necessaria l’approvazione dell’amministratore, completa la connessione come amministratore dell’account o amministratore tecnico e fai clic su Consenti e connetti. Dopo l’approvazione dell’applicazione, i dipendenti potranno accedere autonomamente.

Messaggio o sintomo	Cosa fare
L’applicazione è bloccata dai criteri dell’account	Un amministratore deve approvare l’applicazione specifica o modificare i criteri relativi alle applicazioni di terze parti.
Dopo l’accesso, il client chiede di nuovo l’autorizzazione	Rimuovi la connessione dal client e creala di nuovo. Assicurati di usare l’URL MCP esatto.
È stato selezionato l’account sbagliato	Revoca la connessione e accedi di nuovo selezionando l’account corretto. Non è possibile associare un token a un altro account.
Un’operazione non è disponibile	Controlla gli ambiti concessi e le autorizzazioni di accesso dell’utente in Planfix.