PTC MCP server: connect your coding agent to PTC
The PTC MCP server connects Claude Code, Codex, Cursor and other coding agents to PTC (Private Translation Cloud), the AI localization service for software.
This page has the endpoint, the token, what the server offers and its limits. For what PTC does once your agent is connected, read how the PTC agent guide works. For the set-up commands, see Getting started.
| Item | Value |
|---|---|
| Endpoint | https://app.ptc.wpml.org/mcp |
| Transport | Streamable HTTP: POST only, plain JSON answers, stateless |
| Authentication | Authorization: Bearer <agent token> |
| Agent token | One per person. PTC creates it when you first open the Connect your agent to PTC page, or when you approve the command-line tool's sign-in. The page shows it already filled into the set-up snippet for your client |
| Companion tool | PTC's command-line tool, installed by the agent inside the repository at .ptc/bin/ptc-cli.sh; required |
| Sign-in | You run ptc auth login once in your own terminal and approve it in the browser. The agent never handles the token |
| Ready-made setup for | Claude Code, Codex, Cursor, VS Code. Any other MCP client that can run shell commands connects with the endpoint and the header |
| Tested with | Claude Code, Codex |
| Server name | ptc-guide; its version is the CLI version PTC currently recommends |
What the server offers
The server is a guide, not a translation API. It hands your agent one task at a time and checks each result before handing out the next. It offers five operations:
| Operation | What it does |
|---|---|
| Next task | Returns the next task for this repository with its instructions and payload, or tells the agent that PTC is still working and what to wait for. The first call names the repository (its git remote, or “local” with a project name) and rejoins the repository's existing session if there is one. It can also name a project you began in PTC's setup wizard, and continues it. When a PTC project already uses the repository but no agent session serves it, PTC creates nothing and asks the human: continue that project, or set up a new one. When the token acts in several organizations, the first call returns their list and the agent asks the human which one. |
| Submit | Sends a task's result. PTC answers with a verdict: accepted, rejected, needs more or skipped, each with reasons. Every answer says what comes next. |
| Status | Where the session stands: the stage, the setup progress, the state of every task and the questions waiting for the human. Asked about one task, it returns that task's verdict and reasons. |
| Skip | Skips a task on the human's instruction, with their reason. A task that holds a decision only the human makes cannot be skipped: the census, the conventions, the scope cleanup, the delivery channel, the first sync, the estimate on a paid project, the readiness audit while its gate is open, and writing the configuration while the repository has existing translations to import. PTC's own aids can. |
| Wait | Waits while PTC finishes something on its side (a translation, a check) and returns the verdict and the next task when ready, or asks to be called again. |
Most tasks ask the agent to run a command of PTC's command-line tool and submit its output: scanning the repository, auditing strings, validating a glossary, writing translator notes, reporting a run, syncing translations. The tool prints what to do next on every exit. When PTC requires a newer version, it prints the upgrade command and the guide has the agent install it.
Session model
- One repository has one session. It is identified by the repository's remote URL (any spelling) or, for a checkout without a remote, by a fingerprint of the working tree and a project name. A second agent, another machine or a later day rejoins the same session, and PTC does not create a second project for it. The one exception: when only a project from the setup wizard uses the repository, the human may choose to set up a new one.
- A repository with several products is one suite: a PTC project, with its own session, per product; one MCP connection and one CI secret for all of them.
- Decisions are recorded once and never asked again: languages, conventions, the glossary answer, the estimate, the delivery channel.
- After setup the session stays open for continuous work: every verified CI run reopens only the new or changed strings, and a run with nothing new opens nothing. On a trial, this stops when its two free automatic deliveries are used.
- The session, the project and the token are kept by the command-line tool in the repository's PTC configuration and in a credentials file in the user's home directory; the agent never handles the token.
What the agent is told
Every task carries instructions written for the agent. Three rules run through all of them:
- Relay PTC's questions to the human in PTC's words, and return the human's own words. PTC reads the answer itself and never takes the agent's reading on trust.
- Never answer for the human. Languages, conventions, money, terms and delivery are the human's. What the human already named in the prompt, such as the target languages, counts as their answer and is not asked again.
- Wait on PTC rather than retry. A rejected submission comes back with reasons; the agent fixes and resubmits.
Verification
PTC accepts a result only when it can check it: a scan must come from PTC's own tool; a quoted code line must exist in the files PTC holds for that run; a configuration must come back byte for byte; a source edit counts when PTC's copy of the file shows it; a CI run is proven by the CI platform's own identity token (GitHub Actions, GitLab CI or Bitbucket Pipelines), and a run without one is recorded as unverified. See why an LLM alone is not enough.
Limits
- The agent must run shell commands. There is no MCP-only path.
- The agent's own permission prompts, such as approving a downloaded script or a new MCP tool, are the agent's, not PTC's; expect one or two on a fresh setup. The command-line tool needs bash, curl and Python 3.6 or newer.
- The review covers the translations PTC made. Translations imported from the repository or edited by hand are left as they are.
- The token acts in every organization the person administers; a non-admin's token cannot create projects.
- Money: PTC shows the price and waits for a yes before any paid work. A trial continues within its free allowance and stops only when it reaches a limit. The agent is told to relay PTC's upgrade message and never to purchase on its own.
- A server error or no answer is retried by the command-line tool three times, starting at 5 seconds and doubling. A rate limit that names a delay waits that delay, up to 300 seconds. Any other client error is final at once.
- PTC's in-app guide page is for PTC staff. Customers see progress in the agent's chat and on the PTC dashboard.
Connect
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 and VS Code: the Connect your agent to PTC page gives a ready file for each (.cursor/mcp.json, .vscode/mcp.json) with your token filled in. For any other client, add the endpoint with the Authorization header in its MCP configuration.
Then one prompt: Set up PTC translations.
To continue a project you began in PTC's setup wizard, copy its prompt from the same page, under Continue a project you began in the wizard.
The command-line tool itself is open source (MIT): OnTheGoSystems/ptc-cli.