Server MCP di PTC: collega il tuo agente di programmazione a PTC

Il server MCP di PTC collega Claude Code, Codex, Cursor e altri agenti di programmazione a PTC (Private Translation Cloud), il servizio di localizzazione con IA per il software.

In questa pagina

Cosa offre il server
Modello di sessione
Cosa viene detto all'agente
Verifica
Limiti
Collega

Questa pagina contiene l'endpoint, il token, ciò che il server offre e i suoi limiti. Per scoprire cosa fa PTC una volta collegato il tuo agente, leggi come funziona la guida per gli agenti di PTC. Per i comandi di configurazione, consulta Primi passi.

Elemento	Valore
Endpoint	`https://app.ptc.wpml.org/mcp`
Trasporto	HTTP in streaming: solo POST, risposte in JSON semplice, senza stato
Autenticazione	`Authorization: Bearer <agent token>`
Token dell'agente	Uno per persona. PTC lo crea quando apri per la prima volta la pagina Collega il tuo agente a PTC, o quando approvi l'accesso dello strumento a riga di comando. La pagina lo mostra già inserito nello snippet di configurazione per il tuo client
Strumento di supporto	Lo strumento a riga di comando di PTC, installato dall'agente all'interno del repository in `.ptc/bin/ptc-cli.sh`; obbligatorio
Accesso	Esegui `ptc auth login` una volta nel tuo terminale e lo approvi nel browser. L'agente non gestisce mai il token
Configurazione pronta all'uso per	Claude Code, Codex, Cursor, VS Code. Qualsiasi altro client MCP in grado di eseguire comandi di shell si collega con l'endpoint e l'intestazione
Testato con	Claude Code, Codex
Nome del server	`ptc-guide`; la sua versione è la versione della CLI attualmente consigliata da PTC

Cosa offre il server

Il server è una guida, non un'API di traduzione. Affida al tuo agente un'attività alla volta e ne verifica ogni risultato prima di assegnare la successiva. Offre cinque operazioni:

Operazione	Cosa fa
Attività successiva	Restituisce l'attività successiva per questo repository con le relative istruzioni e il payload, oppure comunica all'agente che PTC sta ancora lavorando e cosa attendere. La prima chiamata nomina il repository (il suo remote di git, o «local» con un nome di progetto) e si ricongiunge alla sessione esistente del repository, se presente. Può anche nominare un progetto che hai iniziato nella configurazione guidata di PTC, e continuarlo. Quando un progetto PTC utilizza già il repository ma nessuna sessione dell'agente lo serve, PTC non crea nulla e chiede all'umano: continuare quel progetto o impostarne uno nuovo. Quando il token opera in diverse organizzazioni, la prima chiamata restituisce il loro elenco e l'agente chiede all'umano quale scegliere.
Invia	Invia il risultato di un'attività. PTC risponde con un verdetto: accettato, rifiutato, richiede altro o saltato, ognuno con le relative motivazioni. Ogni risposta indica cosa succede dopo.
Stato	A che punto si trova la sessione: la fase, l'avanzamento della configurazione, lo stato di ogni attività e le domande in attesa dell'umano. Se interrogato su una singola attività, restituisce il verdetto e le motivazioni di quell'attività.
Salta	Salta un'attività su istruzione dell'umano, con la sua motivazione. Un'attività che contiene una decisione che solo l'umano può prendere non può essere saltata: il censimento, le convenzioni, la pulizia dell'ambito, il canale di consegna, la prima sincronizzazione, il preventivo su un progetto a pagamento, l'audit di preparazione mentre il suo gate è aperto e la scrittura della configurazione mentre il repository contiene traduzioni preesistenti da importare. Gli aiuti di PTC possono esserlo.
Attendi	Attende mentre PTC finisce qualcosa dal canto suo (una traduzione, un controllo) e restituisce il verdetto e l'attività successiva quando è pronto, oppure chiede di essere richiamato.

La maggior parte delle attività chiede all'agente di eseguire un comando dello strumento a riga di comando di PTC e di inviarne l'output: scansionare il repository, controllare le stringhe, convalidare un glossario, scrivere le note per il traduttore, segnalare un'esecuzione, sincronizzare le traduzioni. Lo strumento stampa cosa fare in seguito a ogni uscita. Quando PTC richiede una versione più recente, stampa il comando di aggiornamento e la guida fa in modo che l'agente lo installi.

Modello di sessione

Un repository ha una sessione. È identificata dall'URL remoto del repository (con qualsiasi ortografia) o, per un checkout senza un remote, da un'impronta digitale dell'albero di lavoro e da un nome del progetto. Un secondo agente, un'altra macchina o un giorno successivo si ricongiungono alla stessa sessione e PTC non crea un secondo progetto per questo. L'unica eccezione: quando solo un progetto dalla configurazione guidata utilizza il repository, l'umano può scegliere di impostarne uno nuovo.
Un repository con diversi prodotti è una suite: un progetto PTC, con la propria sessione, per ogni prodotto; una connessione MCP e un segreto CI per tutti.
Le decisioni vengono registrate una volta e mai più richieste: lingue, convenzioni, la risposta del glossario, il preventivo, il canale di consegna.
Dopo la configurazione la sessione rimane aperta per il lavoro continuo: ogni esecuzione CI verificata riapre solo le stringhe nuove o modificate, e un'esecuzione senza novità non apre nulla. In una prova, questo si interrompe quando vengono utilizzate le sue due consegne automatiche gratuite.
La sessione, il progetto e il token vengono conservati dallo strumento a riga di comando nella configurazione PTC del repository e in un file di credenziali nella directory home dell'utente; l'agente non gestisce mai il token.

Cosa viene detto all'agente

Ogni attività contiene istruzioni scritte per l'agente. Tre regole le attraversano tutte:

Riferire le domande di PTC all'umano con le parole di PTC, e restituire le parole stesse dell'umano. PTC legge la risposta in autonomia e non prende mai per buona la lettura dell'agente sulla fiducia.
Non rispondere mai al posto dell'umano. Lingue, convenzioni, denaro, termini e consegna spettano all'umano. Ciò che l'umano ha già nominato nel prompt, come le lingue di destinazione, conta come sua risposta e non viene richiesto di nuovo.
Attendere PTC piuttosto che riprovare. Un invio rifiutato torna indietro con le motivazioni; l'agente corregge e invia nuovamente.

Verifica

PTC accetta un risultato solo quando può verificarlo: una scansione deve provenire dallo strumento stesso di PTC; una riga di codice citata deve esistere nei file che PTC conserva per quell'esecuzione; una configurazione deve tornare indietro byte per byte; una modifica all'origine è valida quando la copia del file di PTC la mostra; un'esecuzione CI è dimostrata dal token di identità della piattaforma CI stessa (GitHub Actions, GitLab CI o Bitbucket Pipelines), e un'esecuzione che ne è priva viene registrata come non verificata. Scopri perché un LLM da solo non basta.

Limiti

L'agente deve eseguire comandi di shell. Non esiste un percorso solo MCP.
I prompt di autorizzazione dell'agente stesso, come l'approvazione di uno script scaricato o di un nuovo strumento MCP, appartengono all'agente, non a PTC; aspettati di riceverne uno o due in una nuova configurazione. Lo strumento a riga di comando richiede bash, curl e Python 3.6 o versioni successive.
La revisione copre le traduzioni effettuate da PTC. Le traduzioni importate dal repository o modificate a mano vengono lasciate così come sono.
Il token agisce in ogni organizzazione amministrata dalla persona; il token di un non amministratore non può creare progetti.
Denaro: PTC mostra il prezzo e attende un sì prima di qualsiasi lavoro a pagamento. Una prova continua entro la sua quota gratuita e si interrompe solo quando raggiunge un limite. All'agente viene detto di riferire il messaggio di upgrade di PTC e di non acquistare mai per conto proprio.
Un errore del server o una mancata risposta vengono riprovati dallo strumento a riga di comando tre volte, partendo da 5 secondi e raddoppiando. Un limite di frequenza delle richieste che indica un ritardo attende quel ritardo, fino a 300 secondi. Qualsiasi altro errore del client è definitivo all'istante.
La pagina della guida in-app di PTC è per il personale di PTC. I clienti vedono l'avanzamento nella chat dell'agente e nel pannello di controllo di PTC.

Collega

Claude Code

claude mcp add --transport http ptc https://app.ptc.wpml.org/mcp --header "Authorization: Bearer <your agent token>"

Codex

export PTC_API_TOKEN='<your agent token>'
codex mcp add ptc --url https://app.ptc.wpml.org/mcp --bearer-token-env-var PTC_API_TOKEN

Cursor e VS Code: la pagina Collega il tuo agente a PTC fornisce un file pronto per ciascuno (.cursor/mcp.json, .vscode/mcp.json) con il tuo token già inserito. Per qualsiasi altro client, aggiungi l'endpoint con l'intestazione Authorization nella sua configurazione MCP.

Poi un solo prompt: Set up PTC translations.

Per continuare un progetto che hai iniziato nella configurazione guidata di PTC, copia il suo prompt dalla stessa pagina, sotto Continua un progetto iniziato nella configurazione guidata.

Lo strumento a riga di comando stesso è open source (MIT): OnTheGoSystems/ptc-cli.