Servidor MCP da PTC: conecte seu agente de codificação à PTC
O servidor MCP da PTC conecta o Claude Code, o Codex, o Cursor e outros agentes de codificação à PTC (Private Translation Cloud), o serviço de localização por IA para software.
Esta página contém o endpoint, o token, o que o servidor oferece e seus limites. Para saber o que a PTC faz depois que seu agente está conectado, leia como o guia do agente da PTC funciona. Para os comandos de configuração, consulte Primeiros passos.
| Item | Valor |
|---|---|
| Endpoint | https://app.ptc.wpml.org/mcp |
| Transporte | HTTP com suporte a streaming: apenas POST, respostas em JSON puro, sem estado |
| Autenticação | Authorization: Bearer <agent token> |
| Token do agente | Um por pessoa. A PTC o cria quando você abre a página Connect your agent to PTC pela primeira vez, ou quando você aprova o login da ferramenta de linha de comando. A página o exibe já preenchido no snippet de configuração do seu cliente |
| Ferramenta complementar | A ferramenta de linha de comando da PTC, instalada pelo agente dentro do repositório em .ptc/bin/ptc-cli.sh; obrigatória |
| Login | Você executa ptc auth login uma vez em seu próprio terminal e o aprova no navegador. O agente nunca lida com o token |
| Configuração pronta para | Claude Code, Codex, Cursor, VS Code. Qualquer outro cliente MCP que possa executar comandos de shell se conecta com o endpoint e o cabeçalho |
| Testado com | Claude Code, Codex |
| Nome do servidor | ptc-guide; sua versão é a versão da CLI que a PTC recomenda atualmente |
O que o servidor oferece
O servidor é um guia, não uma API de tradução. Ele entrega ao seu agente uma tarefa por vez e verifica cada resultado antes de entregar a próxima. Ele oferece cinco operações:
| Operação | O que faz |
|---|---|
| Próxima tarefa | Retorna a próxima tarefa para este repositório com suas instruções e payload, ou informa ao agente que a PTC ainda está trabalhando e o que aguardar. A primeira chamada nomeia o repositório (seu remote do Git, ou “local” com um nome de projeto) e retoma a sessão existente do repositório, se houver. Ela também pode nomear um projeto que você começou no assistente de configuração da PTC e continuá-lo. Quando um projeto da PTC já usa o repositório, mas nenhuma sessão de agente o atende, a PTC não cria nada e pergunta ao humano: continuar aquele projeto ou configurar um novo. Quando o token atua em várias organizações, a primeira chamada retorna a lista delas e o agente pergunta ao humano qual escolher. |
| Enviar | Envia o resultado de uma tarefa. A PTC responde com um veredito: aceito, rejeitado, precisa de mais ou ignorado, cada um com motivos. Cada resposta diz o que vem a seguir. |
| Status | Em que ponto a sessão está: o estágio, o progresso da configuração, o estado de cada tarefa e as perguntas aguardando o humano. Quando questionado sobre uma tarefa, ele retorna o veredito e os motivos dessa tarefa. |
| Ignorar | Ignora uma tarefa sob instrução do humano, com seu respectivo motivo. Uma tarefa que contém uma decisão que apenas o humano toma não pode ser ignorada: o censo, as convenções, a limpeza de escopo, o canal de entrega, a primeira sincronização, a estimativa em um projeto pago, a auditoria de prontidão enquanto sua restrição estiver aberta e a gravação da configuração enquanto o repositório tiver traduções pré-existentes para importar. Os próprios auxílios da PTC podem. |
| Aguardar | Aguarda enquanto a PTC termina algo do seu lado (uma tradução, uma verificação) e retorna o veredito e a próxima tarefa quando estiver pronta, ou pede para ser chamada novamente. |
A maioria das tarefas pede ao agente para executar um comando da ferramenta de linha de comando da PTC e enviar sua saída: verificar o repositório, auditar strings, validar um glossário, escrever notas para tradutores, relatar uma execução, sincronizar traduções. A ferramenta imprime o que fazer a seguir a cada encerramento. Quando a PTC exige uma versão mais recente, ela imprime o comando de atualização e o guia faz com que o agente o instale.
Modelo de sessão
- Um repositório tem uma sessão. Ela é identificada pelo URL remoto do repositório (qualquer grafia) ou, para um checkout sem um remote, por uma impressão digital da árvore de trabalho e um nome de projeto. Um segundo agente, outra máquina ou um dia posterior retoma a mesma sessão, e a PTC não cria um segundo projeto para isso. A única exceção: quando apenas um projeto do assistente de configuração usa o repositório, o humano pode escolher configurar um novo.
- Um repositório com vários produtos é uma suíte: um projeto da PTC, com sua própria sessão, por produto; uma conexão MCP e um segredo de CI para todos eles.
- As decisões são registradas uma vez e nunca mais são solicitadas: idiomas, convenções, a resposta do glossário, a estimativa, o canal de entrega.
- Após a configuração, a sessão permanece aberta para trabalho contínuo: cada execução de CI verificada reabre apenas as strings novas ou alteradas, e uma execução sem nada novo não abre nada. Em um teste gratuito, isso para quando suas duas entregas automáticas gratuitas são usadas.
- A sessão, o projeto e o token são mantidos pela ferramenta de linha de comando na configuração da PTC do repositório e em um arquivo de credenciais no diretório inicial do usuário; o agente nunca lida com o token.
O que é dito ao agente
Cada tarefa carrega instruções escritas para o agente. Três regras se aplicam a todas elas:
- Repassar as perguntas da PTC ao humano nas palavras da PTC, e retornar as próprias palavras do humano. A PTC lê a resposta por si mesma e nunca confia na leitura do agente.
- Nunca responder pelo humano. Idiomas, convenções, dinheiro, termos e entrega são do humano. O que o humano já nomeou no prompt, como os idiomas de destino, conta como sua resposta e não é perguntado novamente.
- Aguardar a PTC em vez de tentar novamente. Um envio rejeitado volta com motivos; o agente corrige e envia novamente.
Verificação
A PTC aceita um resultado apenas quando pode verificá-lo: uma varredura deve vir da própria ferramenta da PTC; uma linha de código citada deve existir nos arquivos que a PTC mantém para aquela execução; uma configuração deve voltar byte por byte; uma edição de origem conta quando a cópia do arquivo da PTC a mostra; uma execução de CI é comprovada pelo próprio token de identidade da plataforma de CI (GitHub Actions, GitLab CI ou Bitbucket Pipelines), e uma execução sem um é registrada como não verificada. Veja por que apenas um LLM não é suficiente.
Limites
- O agente deve executar comandos de shell. Não há um caminho apenas para MCP.
- Os prompts de permissão do próprio agente, como aprovar um script baixado ou uma nova ferramenta MCP, são do agente, não da PTC; espere um ou dois em uma configuração nova. A ferramenta de linha de comando precisa do bash, curl e Python 3.6 ou mais recente.
- A revisão cobre as traduções que a PTC fez. Traduções importadas do repositório ou editadas manualmente são deixadas como estão.
- O token atua em todas as organizações que a pessoa administra; o token de um não administrador não pode criar projetos.
- Dinheiro: a PTC mostra o preço e aguarda um sim antes de qualquer trabalho pago. Um teste gratuito continua dentro de sua cota gratuita e para apenas quando atinge um limite. O agente é instruído a repassar a mensagem de upgrade da PTC e nunca comprar por conta própria.
- Um erro de servidor ou nenhuma resposta é tentado novamente pela ferramenta de linha de comando três vezes, começando em 5 segundos e dobrando. Um limite de taxa que nomeia um atraso aguarda esse atraso, até 300 segundos. Qualquer outro erro de cliente é definitivo imediatamente.
- A página do guia no aplicativo da PTC é para a equipe da PTC. Os clientes veem o progresso no chat do agente e no painel da PTC.
Conecte
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_TOKENCursor e VS Code: a página Connect your agent to PTC fornece um arquivo pronto para cada um (.cursor/mcp.json, .vscode/mcp.json) com seu token preenchido. Para qualquer outro cliente, adicione o endpoint com o cabeçalho Authorization em sua configuração MCP.
Então, um prompt: Set up PTC translations.
Para continuar um projeto que você começou no assistente de configuração da PTC, copie seu prompt da mesma página, em Continue a project you began in the wizard.
A própria ferramenta de linha de comando é de código aberto (MIT): OnTheGoSystems/ptc-cli.