Planfix MCP
MCP (Model Context Protocol) consente agli assistenti AI e ad altre applicazioni compatibili di lavorare con i dati di Planfix attraverso un protocollo standard.
Una volta stabilita la connessione, il client riceve solo le funzionalità esplicitamente autorizzate e opera per conto del dipendente che ha effettuato l'accesso. Restano valide le autorizzazioni di accesso standard di Planfix: un assistente AI non può visualizzare o modificare ciò a cui l'utente non ha accesso.
Le azioni disponibili dipendono dal client MCP, dalle autorizzazioni concesse e dalla versione attuale del server. Ad esempio, un client può essere in grado di trovare compiti e contatti, leggerne i dettagli e aggiungere commenti, se gli vengono concesse le autorizzazioni corrispondenti.
Requisiti
- un account dipendente Planfix (piano a pagamento);
- 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 e-mail.
- 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 l'amministratore è anche la persona che la connette, può approvarla e connetterla con un'unica azione.
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.
Connessione di Codex
Scegli l'opzione in base al fatto che tu sia o meno un amministratore dell'account a cui connetterti.
Se sei un amministratore: connettersi tramite DCR
Questa opzione è disponibile per l'amministratore dell'account o per l'amministratore tecnico. Durante l'accesso, potranno sia approvare l'applicazione registrata automaticamente sia connetterla.
Aggiungi il server MCP:
codex mcp add planfix --url https://mcp.planfix.com/mcp
Avvia l'accesso OAuth e scegli esplicitamente DCR come metodo di registrazione del client:
codex mcp login planfix --oauth-client-registration dcr
Codex aprirà il browser. Seleziona l'account Planfix di cui sei amministratore, controlla le autorizzazioni richieste e fai clic su Consenti e connetti.
Un'applicazione registrata tramite DCR richiede sempre l'approvazione esplicita dell'account. Un dipendente normale non dovrebbe avviare questo scenario: al momento una richiesta di connessione DCR non può essere sospesa e inoltrata a un amministratore per un'approvazione separata.
Il parametro --oauth-client-registration dcr si applica solo a questo accesso e non viene salvato in config.toml. Codex memorizza autonomamente i dati di connessione OAuth ricevuti.
Se non sei un amministratore: connettersi usando client_id
Chiedi prima all'amministratore dell'account o all'amministratore tecnico di creare un'applicazione:
- Apri Gestione account → API → Applicazioni OAuth e MCP.
- Nel blocco Applicazioni di questo account, fai clic su Crea applicazione.
- Inserisci un nome, ad esempio Codex.
- Scegli il tipo Client pubblico. Codex non richiede un segreto client.
- Aggiungi l'URI di reindirizzamento
http://127.0.0.1/callback. - Seleziona le autorizzazioni minime necessarie e salva l'applicazione.
- Fornisci all'utente il
client_idottenuto.
Planfix pubblica l'issuer e supporta l'associazione della risposta di autorizzazione a esso; perciò un nuovo client Codex preregistrato usa il callback stabile http://127.0.0.1/callback. Durante l'accesso, Codex aggiunge una porta temporanea di loopback; Planfix accetta tale porta se l'host e il percorso restano invariati.
L'utente aggiunge il server, sostituendo l'identificatore fornito:
codex mcp add planfix --url https://mcp.planfix.com/mcp --oauth-client-id CLIENT_ID
Codex mostrerà l'URL completo del callback. Nella configurazione predefinita, è simile a questo:
OAuth callback URL: http://127.0.0.1/callback
Se a causa di impostazioni personalizzate di Codex viene mostrato un altro indirizzo, chiedi all'amministratore di aggiungere quell'URI di reindirizzamento all'applicazione.
Poi esegui:
codex mcp login planfix
Specificare --oauth-client-id significa che Codex userà il client preregistrato e non avvierà CIMD o DCR. Le impostazioni vengono salvate approssimativamente in questo modo:
[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"
App Codex ed estensione IDE
L'app Codex, Codex CLI e l'estensione IDE usano una configurazione MCP condivisa sullo stesso computer. Dopo la prima connessione tramite CLI, riavvia l'app o l'estensione. Il server apparirà in Impostazioni → Server MCP. Se accanto ad esso è visualizzato Autentica, fai clic sul pulsante e completa l'accesso.
Puoi controllare i server MCP attivi con il comando /mcp nel campo di immissione di Codex.
L'elenco e lo stato delle connessioni sono consultabili con:
codex mcp list
Gli elementi dell'interfaccia, i comandi e le regole attuali per la selezione del callback sono descritti nella documentazione MCP ufficiale di OpenAI.
Se un altro client MCP non riesce a registrarsi automaticamente
Un client MCP moderno può registrarsi automaticamente tramite CIMD o DCR. Tale registrazione non concede di per sé l'accesso all'account: restano valide le regole dell'account e l'approvazione dell'amministratore.
Se il client richiede un client_id predefinito, chiedi all'amministratore di creare un'applicazione pubblica per l'account:
- Apri Gestione account → API → Applicazioni OAuth e MCP.
- Nel blocco Applicazioni di questo account, crea un'applicazione.
- Scegli il tipo Client pubblico.
- Aggiungi l'URI di reindirizzamento indicato dal client MCP.
- Seleziona le autorizzazioni minime necessarie.
- Fornisci all'utente il
client_idottenuto oppure aggiungilo alle impostazioni del client.
Questa applicazione potrà connettersi solo all'account che l'ha creata. Dettagli — nell'articolo Applicazioni OAuth e MCP in un account.
Più account
Ogni connessione è associata a un account e a un utente.
- Per una connessione DCR, aggiungi un altro server MCP con un nome diverso e, durante l'accesso, scegli un altro account di cui sei amministratore.
- Un'applicazione appartenente a un account e il relativo
client_idfunzionano solo nell'account che li ha creati. Per un altro account, il suo amministratore deve creare un'applicazione pubblica separata; aggiungila a Codex con un nome diverso e il nuovoclient_id.
Non modificare l'URL MCP e non aggiungere il nome dell'account alle richieste. Il server determina l'account in base al token OAuth rilasciato.
Disconnessione di MCP
Per revocare la connessione:
- Apri la scheda utente in Planfix.
- Vai a Gestione sessioni.
- Trova l'applicazione contrassegnata come 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 sono necessari un nuovo accesso e un nuovo consenso.
Un amministratore può revocare un'applicazione per l'intero account in Gestione account → API → Applicazioni OAuth e MCP.
Sicurezza
- Connetti solo le 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. Per un caso d'uso di sola lettura, non concedere autorizzazioni di modifica o eliminazione.
- Non incollare mai un token di accesso o un token di aggiornamento in una chat, nelle impostazioni di una richiesta o nei log.
- Tieni presente che i contenuti di compiti, contatti e commenti potrebbero essere inviati a un servizio AI esterno, in base alle condizioni di trattamento dei dati di tale servizio.
- Rimuovi la connessione da Gestione sessioni se non è più utilizzata o se non la riconosci.
Risoluzione dei problemi
Se l'accesso DCR richiede l'approvazione di un amministratore, accedi come amministratore dell'account o amministratore tecnico e fai clic su Consenti e connetti. Un dipendente normale non può inoltrare per un'approvazione separata una richiesta DCR già avviata.
| Messaggio o sintomo | Cosa fare |
|---|---|
| L'applicazione è bloccata dai criteri dell'account | Un amministratore deve approvare l'applicazione specifica o modificare i criteri per le applicazioni di terze parti. |
| Il client richiede nuovamente l'autorizzazione dopo l'accesso | Rimuovi la connessione dal client e creala di nuovo. Assicurati di usare l'URL MCP esatto. |
| È stato selezionato l'account sbagliato | Revoca la connessione ed effettua nuovamente l'accesso selezionando l'account corretto. Non è possibile passare un token a un altro account. |
Il client richiede un client_id
|
Chiedi all'amministratore di creare un'applicazione pubblica per l'account e aggiungi il server MCP con il parametro --oauth-client-id.
|
| Un'operazione non è disponibile | Controlla gli ambiti autorizzati e le autorizzazioni di accesso dell'utente in Planfix. |