Set Up the MCP Server

What You Are Installing

Nothing, in the usual sense. Your MCP host starts the server itself, over stdio, with npx @the-i18n-kit/mcp@latest — so the version your agent runs is resolved at launch and there is no global install to keep current. Configure the scoped name: the unscoped the-i18n-mcp publishes from the same source at the same versions, and stops receiving updates.

A coverage number your agent reports and a coverage number you get from the-i18n-cli status are the same number — both surfaces call the same operations. See architecture.

You need Node 20 or newer on the machine running the host. You do not need to install the CLI, and you do not need a configuration file to start — the server detects your framework, locales and layers on its first call.

Configure Your Host

Each block below goes in that host's own MCP configuration file. Project-level files sit in your repository, so the server is available to anyone who opens it.

VS Code

{
  "servers": {
    "the-i18n-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@the-i18n-kit/mcp@latest"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "the-i18n-mcp": {
      "command": "npx",
      "args": ["@the-i18n-kit/mcp@latest"]
    }
  }
}

A file at ~/.cursor/mcp.json with the same contents makes the server available in every project instead of one.

Zed

{
  "context_servers": {
    "the-i18n-mcp": {
      "command": "npx",
      "args": ["@the-i18n-kit/mcp@latest"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "the-i18n-mcp": {
      "command": "npx",
      "args": ["@the-i18n-kit/mcp@latest"]
    }
  }
}

The file lives at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%\Claude\claude_desktop_config.json on Windows. Claude Desktop reads it at startup, so restart the app after editing it.

Confirm the Server Is Running

Two checks, in increasing order of how much they prove.

The package resolves. Run the server yourself:

npx -y @the-i18n-kit/mcp@latest

It prints nothing and waits for JSON-RPC on stdin. Silence is the passing result; press Ctrl-C to stop it. An error here is a Node or network problem, not a host problem.

The host reached your project. Ask your agent to call discover. It is the tool the server documents as the one to call first, and its answer is a summary of what the kit thinks your project is:

{
  "rootDir": "/srv/app",
  "framework": "vue",
  "defaultLocale": "en-US",
  "locales": [
    { "code": "de-DE", "language": "de-DE", "file": "de-DE.json" },
    { "code": "en-US", "language": "en-US", "file": "en-US.json" },
    { "code": "es-ES", "language": "es-ES", "file": "es-ES.json" },
    { "code": "fr-FR", "language": "fr-FR", "file": "fr-FR.json" }
  ],
  "layers": [
    {
      "layer": "root",
      "path": "/srv/app/src/translations",
      "fileCount": 4,
      "topLevelKeys": ["booking", "common"]
    }
  ],
  "protectedLocales": ["de-DE"],
  "translationMode": "agent"
}

Read three fields off it before going further:

• framework — which adapter won detection. If it is not the one you expected, see detection for how to pin one.
• layers — one entry per layer, meaning a scoped locale directory: a Nuxt layer, a workspace package, a shared UI library, or one app in a monorepo. A layer you expected and do not see is a locale directory the adapter did not find.
• translationMode — agent or provider, decided at server startup. The next section is about that field.

Choose Which Model Translates

translate_missing and translate_key run in one of two modes, resolved once when the server starts. discover reports the active one, so you can check the configuration without spending a translation to find out.

Agent mode is the default and needs no configuration. The translate tools return per-locale fallback contexts — the source values plus the glossary, tone notes and locale notes from your config file — and your host agent translates them with its own model, then writes the results back with write_translations. The keys never leave the conversation you are already having.

Provider mode has the server call an LLM provider directly, validate what comes back and write it. Set the environment variables on the server process, in the same host configuration block:

{
  "servers": {
    "the-i18n-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["@the-i18n-kit/mcp@latest"],
      "env": {
        "I18N_PROVIDER": "google",
        "I18N_MODEL": "gemini-2.5-flash",
        "GEMINI_API_KEY": "<your-api-key>"
      }
    }
  }
}

Substitute your own key for <your-api-key>.

Set some of these and not all of them and the server logs a warning to stderr and starts in agent mode. The mode is decided once, at startup, rather than per request, so a half-configured server cannot surprise a caller mid-conversation — but it also means a config edit needs a host restart to take effect.

Give the Server Your Terminology

Detection finds your locale files. It cannot know that "Booking" is a product concept or that your formal German locale is maintained by a person and must not be machine-translated. Both belong in a config file at your project root, which the server reads on every call:

import { defineI18nKitConfig } from '@the-i18n-kit/cli/config'

export default defineI18nKitConfig({
  context: 'A B2B booking platform.',
  glossary: { anny: 'Brand name. NEVER translate.' },
  protectedLocales: ['de-formal'],
})

protectedLocales is the one to set first: locales named there are excluded from default translate targets and reported as skipped with the reason protected-locale, in both modes. See where configuration lives for the two files that accept these fields and how each is found, and the field reference for everything they accept.

What Your Agent Can Do Now

Every tool the server advertises, with the parameters a host receives, is on the MCP tools reference — generated by starting the server and reading its own tools/list response, so it cannot list a tool your host is not offered.

Three things worth knowing before you point an agent at a large project:

• Results that could run to thousands of keys accept an outputFile parameter. Given an absolute path, the tool writes its full JSON result there and returns a compact summary, so a repository-wide scan does not land in the context window. The tools reference lists which tools accept it.
• remove_orphan_keys is dry-run by default, and an uncertain key — one whose usage evidence is ambiguous — is never removed, even when you confirm.
• The same operations exist as CLI commands, paired one to one. If you want to see what a tool would do before letting an agent do it, run the paired command from the CLI reference.

Limits

• The server works on the project directory the host launches it in, and every tool accepts a projectDir parameter to point elsewhere. An agent working in a directory you did not expect reports it in discover as rootDir — check that field before trusting a coverage number.
• MCP sampling was removed. The server no longer asks the host to pick a model, and samplingPreferences in .i18n-mcp.json is accepted and ignored. Provider mode is the replacement for server-side translation.
• Detection runs per call and is mtime-cached. Adding a locale directory while the server is running is picked up; changing which framework the project looks like is better followed by a host restart.