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

The Better i18n MCP server lets coding agents — Claude Code, Cursor, Windsurf, Zed, Codex — manage your translations and content: create keys, translate, publish, edit content entries.

Two ways to connect #

Remote (recommended, no API key). Agents that speak remote MCP sign in with OAuth:

Code

https://mcp.better-i18n.com/mcp

In Cursor: Settings → MCP → Add new MCP server → Remote, paste that URL, and your browser opens to sign in on first use.

In Claude Code:

Bash

claude mcp add --transport http --scope user better-i18n https://mcp.better-i18n.com/mcp

Local bridge (needs an API key). For agents that only run stdio servers:

JSON

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

Or in one line:

Bash

claude mcp add better-i18n -s user -e BETTER_I18N_API_KEY=bi-... -- npx -y @better-i18n/mcp@latest

Account keys look like bi-… (Settings → API Keys). Content delivery keys (bi_pub_…) are read-only and will not work here.

For ChatGPT, Claude on the web or Gemini, use the AI Assistants setup instead — nothing to install.

Project context #

The server needs to know which project it is managing. It reads projectId from your i18n.config.ts:

TypeScript

export const i18n = createI18n({
  projectId: "your-org/your-project",
  defaultLocale: "en",
});

Two servers, two toolsets #

Package	Covers
`@better-i18n/mcp`	Translation keys, languages, publishing, sync history
`@better-i18n/mcp-content`	Content CMS models, fields, entries

Add the content server the same way when your project uses the CMS.

Translation tools #

Tool	What it does
`listProjects` · `getProject`	Discover projects; languages, namespaces, coverage
`listKeys`	Browse keys, compact and paginated
`getTranslations`	The actual translation text — what an AI task needs
`createKeys` · `updateKeys` · `deleteKeys`	Manage keys
`setTranslations`	Write translation values
`getTranslationContext`	Surrounding context for a key, so a translation is not guessed blind
`proposeLanguages` · `proposeLanguageEdits`	Suggest languages or edits for review instead of applying them
`getPendingChanges`	What would go live on the next publish
`publishTranslations`	Publish to the CDN
`getSyncs` · `getSync` · `cancelSync`	Sync history and control

Content tools #

Tool	What it does
`listContentModels` · `getContentModel`	Inspect schemas
`createContentModel` · `updateContentModel` · `deleteContentModel`	Manage schemas
`addField` · `updateField` · `removeField` · `reorderFields`	Manage fields
`listContentEntries` · `getContentEntry`	Find and read entries
`createContentEntry` · `updateContentEntry` · `duplicateContentEntry`	Write entries
`bulkCreateEntries` · `bulkUpdateEntries`	Up to 200 entries per call, partial failures reported
`publishContentEntry` · `bulkPublishEntries`	Publish (up to 500 ids in bulk)
`deleteContentEntry`	Move an entry to Trash

Two habits that save calls: pass every language in the initial createContentEntry rather than looping updates, and use missingLanguage=fr — not language=fr — to find what still needs translating.

Example prompts #

Code

"Add common.save_button with value 'Save' and translate it to Turkish, French and Spanish"

"Find keys in the auth namespace that have no German translation and translate them"

"Show me what would go live if I published right now"

"Create a help article about getting started, translate it to every project language, publish it"

What agents can and cannot do #

They work through the tools above — so keys, translations, languages, publishing, content and sync history are in scope.

Billing, deleting a project or an organisation, and inviting team members are not: there is no tool for any of them, which is a stronger guarantee than a permission setting. Deleting an entry is the softest destructive action available, and it goes to Trash rather than disappearing.

Seeing what the agent did #

MCP operations land in the project's activity log attributed to an agent rather than to a person, so a run you did not watch is still reviewable afterwards.