How do I use the MCP server with AI coding agents?

The Better i18n MCP (Model Context Protocol) server lets AI coding agents manage your translations directly. Create keys, update translations, check sync status — all from natural language commands in your IDE.

What is MCP?

MCP is a protocol that lets AI agents interact with external tools. When you connect the Better i18n MCP server, your AI agent can:

• List and search translation keys
• Create new keys with values
• Update translations across languages
• Check sync status and find missing translations
• Publish changes to the CDN
• Manage content via the Content SDK

Setup

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "better-i18n": {
      "command": "npx",
      "args": ["-y", "@better-i18n/mcp"],
      "env": {
        "BETTER_I18N_API_KEY": "sk_..."
      }
    }
  }
}

Cursor / Windsurf

Add to your IDE's MCP settings (usually in Settings → MCP Servers):

{
  "better-i18n": {
    "command": "npx",
    "args": ["-y", "@better-i18n/mcp"],
    "env": {
      "BETTER_I18N_API_KEY": "sk_..."
    }
  }
}

Note: Use a secret key (sk_...) for the MCP server, not a public key. The MCP server needs write access.

Example workflows

Adding keys while coding

You: "I'm adding a settings page. Create translation keys for
      settings.title, settings.save_button, and settings.cancel_button
      with English values."

Agent: Uses createKeys tool to add all three keys with values.

Translating

You: "Translate all untranslated keys in the 'settings' namespace to Turkish."

Agent: Uses getTranslations to find gaps, then proposeLanguageEdits
       to add Turkish translations.

Checking status

You: "Are there any keys missing Turkish translations?"

Agent: Uses listKeys with language filter to find untranslated keys.

Publishing

You: "Publish all pending translations."

Agent: Uses publishTranslations to push changes to CDN.

Content management

There's also a separate MCP server for content management:

{
  "better-i18n-content": {
    "command": "npx",
    "args": ["-y", "@better-i18n/mcp-content"],
    "env": {
      "BETTER_I18N_API_KEY": "sk_..."
    }
  }
}

This enables managing structured content models and entries — blog posts, changelogs, help articles, and more.

Security considerations

• The MCP server runs locally on your machine
• Your API key stays in your local environment
• The agent can only perform actions within your project's permissions
• All changes are audited in the dashboard activity log

Supported agents

Any MCP-compatible agent works, including:

• Claude Code (CLI)
• Claude Desktop
• Cursor
• Windsurf
• Continue
• Custom agents built with the MCP SDK

Next steps

• MCP documentation
• AI translation quality