MCP Integration

The bi_oat_ installation token works directly with the Better i18n MCP server — no additional setup needed. This means your users' AI coding agents can manage translations through the same scoped token.

How it works

AI Agent (Cursor, Claude Code, ChatGPT)
  ↓ MCP Protocol
@better-i18n/mcp server
  ↓ x-api-key: bi_oat_...
api.better-i18n.com
  ↓ scope enforcement
Resource APIs

The MCP server sends the token via x-api-key header. The API recognizes bi_oat_ tokens from the apikey table and enforces the same scope rules as REST.

Configure the MCP server

stdio transport (Cursor, Claude Code)

Add to your IDE's MCP config (e.g., .cursor/mcp.json):

.cursor/mcp.json

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

HTTP transport (ChatGPT, Codex, Agents SDK)

Send the token as a Bearer header to the MCP HTTP endpoint:

curl -X POST https://mcp.better-i18n.com/mcp \
  -H "Authorization: Bearer bi_oat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ ... MCP request ... }'

Available MCP tools

With a scoped bi_oat_ token, your agent can call:

Tool	Required scope
`listProjects`	`projects:read`
`getProject`	`projects:read`
`listKeys`	`keys:read`
`createKeys`	`keys:write`
`updateKeys`	`translations:write`
`setTranslations`	`translations:write`
`deleteKeys`	`keys:write`
`getTranslations`	`translations:read`
`publishTranslations`	`translations:publish`
`getTranslationContext`	`projects:read`

If a tool requires a scope the token doesn't have, the API returns 403 missing_scope — the agent surfaces this to the user.

Partner auto-inject pattern

If you're a platform partner (like Loveable, Replit, Bolt), you can auto-configure MCP for your users:

After OAuth consent, you have a bi_oat_ token
Write a .cursor/mcp.json (or equivalent) to the user's workspace
The user's AI agent immediately has translation capabilities

This is the agent-native differentiator — no competitor offers scoped, consent-driven MCP integration.

Scope enforcement

MCP tools hit the same API endpoints as REST calls. A token with only keys:read + translations:read can list and read translations but cannot create keys or publish. The scope boundary is enforced at the API middleware level, not at the MCP layer.