Coding agents (MCP)
Your coding agent works on your translations the way you do in the
editor: it finds untranslated text, stages translations, previews the
diff and opens the minimal-diff pull request. It connects to Dialecto’s
MCP server at https://app.dialecto.eu/mcp as you, with your role on
each project, so it can do nothing your account can’t.
It needs a Dialecto account, and accounts are open: sign up free.
Token
Open Settings from the account menu and choose Generate token on the Agent access card. Dialecto shows the token once and keeps only a fingerprint of it, so copy it straight away, or use Connect, which holds the setup prompt and both commands below with your token already in them.
A token lasts 365 days. You hold one at a time: Regenerate token stops the old one the moment the new one exists, and Revoke… stops it outright, so an agent you no longer trust loses access with one click.
Setup prompt
Paste this into Claude Code in your app’s folder, with your token in
place of <token>. Your agent connects to Dialecto and adds the
repository as a project once you approve the translation files it found.
Adding a project needs the owner or admin role in your organization, and
the Dialecto GitHub App installed on the repository or on All
repositories.
Set up Dialecto for this repository.
1. Run: claude mcp add --scope user --transport http dialecto https://app.dialecto.eu/mcp --header "Authorization: Bearer <token>"
2. Ask me to restart this session so the dialecto tools load, then continue.
3. Ask me whether Dialecto should read this repository through the GitHub App, or use Security mode, where Dialecto holds no access to the repository. Find its GitHub address (git remote get-url origin). For Security mode, list the translation files with git ls-files '*.po' '*.pot' '*.json' '*.yml' '*.yaml' '*.php' '*.xcstrings' '*.resx' '*.resw' and pass them as paths with mode security. Call add_project, show me the translation files it proposes and wait for my yes before calling it again with confirm true. For Security mode, then run the commands it returns, commit the workflow file it gives, and push.
4. Call project_setup for the new project and list anything still missing, with its link.
Claude Code
Run this once in a terminal, with your token in place of <token>:
claude mcp add --scope user --transport http dialecto https://app.dialecto.eu/mcp \
--header "Authorization: Bearer <token>"
claude mcp list then shows dialecto as connected. With --scope user,
every folder on your machine has the tools.
Cursor
Add Dialecto to ~/.cursor/mcp.json, or to .cursor/mcp.json in one
project:
{
"mcpServers": {
"dialecto": {
"url": "https://app.dialecto.eu/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}
Other MCP clients that speak Streamable HTTP take the same URL and header.
Tools
Every tool runs as you and checks your role on the project first. A tool that fails returns its reason to the agent, which can then fix its call.
| Tool | Purpose |
|---|---|
list_projects |
Your projects: ID, repository, source and target languages |
add_project |
Adds a GitHub repository as a project: without confirm it lists the translation files it found, and with confirm true it creates the project and starts the first sync. With mode security and paths (the repository’s candidate files from git ls-files) it needs no GitHub App: the project is created in Security mode, and the result gives a single-use command that stores the scan token as the repository’s Actions secret without the token appearing in the chat, the command that lets workflows open pull requests, and the workflow file to commit |
project_setup |
The steps a project still needs, each with its page: GitHub App, catalog paths, last sync, languages and untranslated text per language |
list_domains |
The project’s domains, each with its string count, so your agent can work one domain at a time |
search_strings |
Finds strings by text, key or domain, with entry IDs, keys, English and one language’s translation |
list_untranslated |
A language’s untranslated and outdated text, with entry IDs and keys; an outdated entry also carries its earlier English |
get_voice_card |
The project’s brand voice for a language |
stage_translation |
Stages one translation for review, never a pull request |
update_source_text |
Stages a new English text for one entry in a project whose strings have keys, and names the translations that become outdated |
rename_keys |
Stages the rename of one key, or of every key under a prefix, in every language file, with the code that reads them planned for the pull request |
preview_diff |
The minimal diff of everything staged, including renames and source text |
discard_change |
Drops one staged change; a key in a staged rename takes the whole rename back |
open_pr |
Opens the pull request for the approved changes |
Staged translations go through the same review as the editor’s: the merge gate and, when it is on, the quality gate still apply. Ask your agent something like “translate the untranslated French text in acme/web and show me the diff”, and it finds the project, drafts in your brand voice and stops at the diff for your review.
Key renames
rename_keys works as the editor’s rename does. A prefix ends with the
key separator, so basket. to cart. renames every key under it, and
anything else renames one key. Where the source text is the key, as in
gettext and Django, a rename always moves one message. The rename needs
the Developer role or higher, and a project whose format and framework
rename keys with their code. When any key in the rename can’t move, the tool stages nothing and
tells your agent which key and why. Ask your agent something like
“rename the basket. keys to cart. in acme/web and show me the diff”.