Skip to content

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

  1. Apri le impostazioni del server MCP nel client.
  2. Aggiungi un nuovo server usando il trasporto Streamable HTTP.
  3. Inserisci un nome, ad esempio Planfix, e l'URL MCP.
  4. Salva le impostazioni e avvia l'autenticazione OAuth.
  5. Nella finestra del browser che si apre, seleziona il tuo account Planfix. Puoi trovarlo per nome, URL o indirizzo e-mail.
  6. 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:

  1. Apri Gestione account → API → Applicazioni OAuth e MCP.
  2. Nel blocco Applicazioni di questo account, fai clic su Crea applicazione.
  3. Inserisci un nome, ad esempio Codex.
  4. Scegli il tipo Client pubblico. Codex non richiede un segreto client.
  5. Aggiungi l'URI di reindirizzamento http://127.0.0.1/callback.
  6. Seleziona le autorizzazioni minime necessarie e salva l'applicazione.
  7. Fornisci all'utente il client_id ottenuto.

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:

  1. Apri Gestione account → API → Applicazioni OAuth e MCP.
  2. Nel blocco Applicazioni di questo account, crea un'applicazione.
  3. Scegli il tipo Client pubblico.
  4. Aggiungi l'URI di reindirizzamento indicato dal client MCP.
  5. Seleziona le autorizzazioni minime necessarie.
  6. Fornisci all'utente il client_id ottenuto 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_id funzionano 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 nuovo client_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:

  1. Apri la scheda utente in Planfix.
  2. Vai a Gestione sessioni.
  3. Trova l'applicazione contrassegnata come MCP ed elimina la sessione.
  4. 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.

Vai a