MCP Server - Tool Reference

Table of Contents

• Overview
• Transport & Authentication
• Read Tools
• Write Tools
• Configuration Tools
• Error Handling
• Back to Quick Start

Overview

The MCP server exposes 16 tools, all scoped to the single project your Server API Key belongs to. Each tool maps to the same engine used by the CLI and web app, so validation, placeholder protection, translation memory, and protected words behave identically.

New to this? Start with the MCP Quick Start Guide.

Transport & Authentication

• Endpoint: https://www.gettranslated.ai/mcp/translate/
• Transport: JSON-RPC 2.0 over HTTP POST (MCP Streamable HTTP). The server is stateless and does not open a server-to-client SSE stream.
• Auth: Authorization: Bearer <key> on every request. Two kinds of key work:
  • Project server key (sk-…, from a project's settings page) — scoped to that one project. Best for CI and embedded apps. Key rotation honors a short grace period for the previous key.
  • User token (uk-…, from your account settings) — scoped to you, and can act on any project in your organization. You choose the project per request by passing a project argument (the project's client key, ck-…); call list_projects to discover them. Best for interactive / agent use across multiple projects, without reconnecting.

Read Tools

list_projects

Lists the projects this credential can act on. Each entry has a project selector (the project's client key), name, platform, base language, and target languages. With a user token (uk-) this returns every project in your organization — call it first, then pass the chosen project value to other tools. With a project server key (sk-) it returns the single bound project.

Arguments: none.

get_project

Returns project metadata and translation config: name, platform, base/target languages, model, protected words, tone, translation-memory flag, and last sync time. Terminology is returned two ways: terminology (the project's own, editable layer) and effective_terminology (the project merged with any organization-wide shared terminology — what actually applies at translation time).

Arguments: none.

get_translation_status

Returns counts of strings and translations, percent translated, untranslated count, monthly active users, validation-issue count, and grammar-check progress.

Arguments: none.

list_files

Lists source files and the per-language download URIs and local paths.

Arguments: none.

list_validation_issues

Lists validation issues grouped by file and by type (placeholder mismatches, plural forms, duplicate keys, unsafe characters). Each issue carries an id for fix_validation_issue, and the response includes an auto_fixable_count.

Arguments: none.

list_grammar_recommendations

Lists pending grammar/spelling recommendations for the base language. Each entry has a string_id (for accept/reject), the current text, the suggested text, and an explanation. Recommendations are generated automatically as part of translate.

Arguments: none.

download_file

Returns a translated (or base-language) file's contents in platform-native format.

Arguments:

• file (required) — source file path, e.g. values/strings.xml
• language (required) — language code, e.g. es

get_translations

Returns current translations for a target language as a structured { key: value } map (not a file blob) — ideal after a scoped translate for applying just the affected keys in your editor. Returns { language, ref, translations }, plus missing_keys (requested keys not translated yet) when keys is given. The echoed ref is the branch the result reflects — if it isn't the branch you meant, pass ref. Plural values come back in their stored JSON form.

Arguments:

• language (required) — target language code, e.g. es (not the base language)
• keys (optional) — return only these source keys
• file (optional) — restrict to one source file path

Write Tools

upload_source

Parses and syncs a localization file's contents. Returns new/changed/deprecated key counts plus any validation errors or warnings. Defaults to the project's base language.

This upload is authoritative for the file: keys present in the project but absent from the content you send are marked deprecated. Always send the complete file, never an excerpt. For large files (roughly >100 KB) the server rejects the upload — reproducing them inline risks truncation (and mass deprecation of the dropped keys); sync those with the CLI (translate sync) instead.

Arguments:

• file_name (required) — source file path, e.g. values/strings.xml
• content (required) — full file contents as text
• language (optional) — defaults to the project base language

translate

Runs one bounded translation batch and returns { translated, percent_done, continue }. Loop while continue is true. A single call will not finish a large project — that's by design, to stay within request timeouts.

Arguments (all optional):

• keys — a list of source keys to translate only those (e.g. the strings you just synced with upload_source), instead of every untranslated string. Keys must already exist as translatable source strings; unknown keys are rejected.
• file — restrict translation to one source file path. Recommended alongside keys to disambiguate a key name that recurs across files.

Omit both to translate every untranslated string. Note: percent_done always reflects whole-project progress, not just the scoped keys — loop on continue, not percent_done.

set_translation

Manually sets or overrides the translation of a single key for one target language — e.g. correcting a wrong AI translation. The value is stored as a new version (mirroring the dashboard's manual edit) and re-validated on the next validation pass, so a placeholder mismatch will surface in list_validation_issues rather than being silently accepted. Base-language and plural/array keys are out of scope.

Arguments:

• key (required) — source key, e.g. welcome_title
• language (required) — target language code, e.g. es (must be one of the project's target languages, not the base language)
• value (required) — the translation text to store
• file (optional) — source file path, to disambiguate a key that recurs across files

accept_grammar_recommendation

Accepts a pending grammar recommendation, applying its suggested text as a new version of the string.

Arguments:

• string_id (required) — the string_id from list_grammar_recommendations

reject_grammar_recommendation

Rejects a pending grammar recommendation, leaving the current text unchanged.

Arguments:

• string_id (required) — the string_id from list_grammar_recommendations

accept_grammar_recommendations

Accepts several pending grammar recommendations in one call — pass the list of string_ids instead of calling accept_grammar_recommendation repeatedly. Ids with no pending recommendation (already actioned or unknown) are skipped and returned in not_found, so a stale id never fails the batch. To accept every pending recommendation, pass all their ids.

Arguments:

• string_ids (required) — a list of string_ids from list_grammar_recommendations

reject_grammar_recommendations

Rejects several pending grammar recommendations in one call — pass the list of string_ids instead of calling reject_grammar_recommendation repeatedly. Ids with no pending recommendation are skipped and returned in not_found.

Arguments:

• string_ids (required) — a list of string_ids from list_grammar_recommendations

fix_validation_issue

Auto-fixes a single validation issue. Only auto-fixable types (unsafe characters, duplicate keys) can be fixed; other types must be resolved by editing the source file and re-uploading.

Arguments:

• issue_id (required) — the id from list_validation_issues
• selected_value (optional) — for duplicate-key issues, which value to keep; defaults to the first

fix_all_validation_issues

Auto-fixes every auto-fixable validation issue (unsafe characters, duplicate keys) at once and returns the number fixed. Issues that aren't auto-fixable are left untouched.

Arguments: none.

Configuration Tools

set_protected_words

Replaces the project's entire protected-words list (brand names/terms left untranslated). Omitting a currently-protected word unprotects it and re-translates its strings — to add or remove a single word, prefer add_protected_words / remove_protected_words below. Translations of impacted strings are invalidated so they re-translate on the next translate run. Requires a plan with protected words.

Arguments:

• words (required) — full replacement list of strings (not a delta)

add_protected_words

Adds words to the protected-words list (union), leaving every other protected word and glossary override untouched — the safe, additive alternative to set_protected_words. Only the newly-added words' non-conforming translations re-translate. Requires a plan with protected words.

Arguments:

• words (required) — protected words to add (deduped against the existing list)

remove_protected_words

Removes words from the protected-words list, leaving every other protected word and glossary override intact. Unprotecting a word re-translates its strings. Only project-level protected words are affected. Requires a plan with protected words.

Arguments:

• words (required) — protected words to remove (ignored if not currently protected)

set_glossary

Replaces the entire glossary — per-language forced translations for specific terms. Maps each term to {language_code: translation}, e.g. {"watch": {"fr": "montre", "de": "Uhr"}}. Any term/language override you omit is dropped — to add or remove a single override, prefer add_glossary_terms / remove_glossary_terms below. Protected-word flags on existing terms are preserved. Invalidates impacted translations so they re-translate on the next translate run. Requires a plan with the glossary feature.

Arguments:

• glossary (required) — full replacement map of term → {language_code: translation}

add_glossary_terms

Adds per-language forced translations to the glossary (merge), leaving every other term, other languages' overrides, and protected-word flags untouched — the safe, additive alternative to set_glossary. Requires a plan with the glossary feature.

Arguments:

• glossary (required) — map of term → {language_code: translation} to merge in, e.g. {"watch": {"fr": "montre"}}

remove_glossary_terms

Removes all glossary overrides for the given terms (whole-term removal), leaving every other term and any protected-word flags intact. Only project-level overrides are affected. Requires a plan with the glossary feature.

Arguments:

• terms (required) — terms whose glossary overrides should be removed

set_tone

Sets the AI translation tone. Requires a plan with AI tone tuning.

Arguments:

• tone (required) — one-letter code: N Neutral, F Friendly, C Casual, P Professional, R Reassuring, D Direct, M Motivational, Y Playful

set_languages

Replaces the project's target languages (full list, not a delta). Each code must be available on your plan tier; the base language is not a valid target. Translations for removed languages are kept in history but no longer active.

Arguments:

• languages (required) — full replacement list of target language codes, e.g. ["es", "fr"]

set_model

Sets the default AI model used for this project's translations. Requires a plan with multiple LLMs. New translations use the selected model; existing translations are left unchanged (this does not re-translate). See get_project for the current default_model.

Arguments:

• model (required) — a valid model id, e.g. gpt-6-luna

set_translation_memory

Enables or disables translation memory (reuse of prior translations of identical source text) for the project. Requires a plan with translation memory.

Arguments:

• enabled (required) — true to enable, false to disable

set_default_branch

Sets (relabels) the project's default branch/ref — the branch used when a request omits a ref. Use it when a project was created defaulting to main but your canonical branch has another name (e.g. develop): it renames the default in place, keeping all strings and translations (only the label changes); other branches are untouched. Fails only if a branch with the new name already exists — delete or promote that branch first. See get_project for the current default_ref.

Arguments:

• branch (required) — the new default branch/ref name, e.g. develop

delete_branch

Deletes a non-default branch and its data (per-branch strings/translations that no other branch uses are cleaned up). Use it to clear a stray branch — e.g. one created by mistake when a call passed a ref that wasn't the project's default. Refuses the default branch.

Arguments:

• branch (required) — the name of the branch/ref to delete (not the default)

Error Handling

The server distinguishes two error classes:

• Tool errors (bad arguments, plan limits, validation failures, language not in plan) return an MCP tool result with isError: true and a descriptive message, so your AI client can read it and self-correct.
• Transport errors (missing/invalid auth, malformed request, unknown method) return a JSON-RPC error with a non-2xx HTTP status.

Internal errors never include server stack traces or internal details in the response — they return a generic message and are logged server-side.