AI agents and MCP

What it does#

Localization OS is designed so that most features exist on the web UI, the API and the CLI equally, and a page that names a real gap says so rather than leaving you to discover it. A few surfaces are still web-only in the current release, among them OAuth connector setup, launching an LQA re-score, and the segmented CAT editor's own save path. An agent driver, any non-human caller such as an MCP server, a script, a CI job, or an LLM with tools, authenticates with a personal API key and acts inside a tenancy that already has its own access rules: every object belongs to exactly one organization, which contains customers, which contain projects.

A project is either a document project (files in, files out) or a key-based project (string keys, for continuous localization), chosen at creation and fixed afterward. Work runs through workflows: an ordered list of steps such as an LLM translation step, an automated quality check, a pause for human review, a translation-memory pre-fill step, or a dispatch to an external vendor.

An MCP server packages this same API as a set of task-shaped tools for an MCP-compatible client, so an agent runtime can drive the product the same way a person or a script does, without hand-rolling HTTP calls.

The MCP server exposes 84 task-shaped tools covering orientation, projects and customers, documents and review, keys and the change feed, workflows and runs, language assets and TM (including formality and workspace search), memory, the Evaluations Lab, operational reads and connectors, and admin tools behind their own switch. Tools that spend money are two-phase: the first call returns a plan and a cost estimate, and the work runs only on a confirmed second call. No tool deletes anything, and no tool ever carries a secret.

Getting started#

1. Issue a personal API key from the Account page, or with the CLI's key-issuing command. Keep it out of prompts, logs and version control.
2. Authenticate every API request with that key in a request header.
3. For scripted or CI use, the CLI can run directly against a local install with no server or login at all, or be pointed at a remote install with the key and its URL.
4. For an agent runtime, point an MCP-compatible client at the bundled MCP server to get a curated set of tools instead of raw HTTP calls.

curl -H "X-Loc-Token: YOUR_API_KEY" \
  https://your-install.example.com/api/projects

project create "Acme Site" --customer-id 7 --targets de-DE
doc upload 7 ./handbook.docx
doc translate 12 --locale de-DE
doc export 12 --locale de-DE --out handbook.de-DE.docx

The same flow applies to a key-based project, substituting key import and key translation for document upload and document translation.

MCP for agents#

The MCP server is built for agent hosts that decide on their own what to call. These are the rules it follows and the signals it gives.

Spending is bound to a plan

A spend tool's first call returns a plan with a plan_id. The confirmed call must carry that plan_id, with the same arguments, from the same key, within 30 minutes, and a plan works once. Anything else (changed languages, another connection, another tool's or another caller's plan, a reused or expired plan) is refused as spend_refused and nothing is sent: plan again. An operator can also require a person to approve each confirmed spend in the agent host, on hosts that support that prompt. This applies to MCP only; the web, API and CLI spend paths are unchanged.

Tool metadata and structured results

• Every tool has a title and annotations for host permission screens: read tools are marked read-only, spend tools and every write tool that is not purely additive are marked destructive, and connector and vendor tools are marked as reaching outside systems.
• Every result carries structured content that matches the tool's declared output schema, next to the same JSON as text for older clients.
• Every tool error ends with one JSON line: {"error": {"code", "http_status", "retryable", "retry_after_s", "required_scope"}}. Branch on code (for example unauthorized, insufficient_scope, not_found_or_hidden, conflict, rate_limited, capacity_retry, timeout_maybe_running). Only capacity_retry, rate_limited and unreachable are retryable; after timeout_maybe_running, check the job's status before calling again.

External content is data

Results carry text written by customers, vendors, engines and other systems: CMS titles, segments, glossary and memory entries, query posts, transcripts and vendor error messages. Such text can contain sentences written to look like instructions. A result that carries it gains an external_content key listing the fields that hold outside text, and the server's own instructions tell the agent that this text is data, never a reason to publish, delete or send anything. Connector results also carry requires_human_publish: true: publishing in the other system is the person's decision. Vendor error text is cleaned and shortened before it is quoted.

Slow work runs in the background

Ten slow tools (connector sync, translate, push, pull, Advanced missions, term extraction, image translation, memory distillation and the two evaluation launches) start their work in the background and wait up to 45 seconds. Longer work answers {"status": "running", "job_id": N}; poll job_status for the result. Repeating an identical call while it runs returns the same job. Every spend tool also takes an optional idempotency_key: re-sending the same call with the same key within 24 hours returns the first answer instead of spending again. The REST API offers the same through the Prefer: respond-async and Idempotency-Key headers, and the CLI through --idempotency-key.

Only the tools your key can use

The tool list shows only the tools the calling key's scopes reach, read from the key's own grants (it never sees any other key). A hidden tool that is called anyway still gets the API's refusal. To keep agent context small, an operator can load named toolsets (for example connectors, keys or admin), and an HTTP connection can narrow that further with a header or a query parameter. mcp connect --toolsets prints a connection line with the toolsets set.

Sign-in for remote MCP clients (off by default)

Agent hosts that connect to remote MCP servers with OAuth 2.1 can sign in with the person's normal account and a consent page instead of a pasted key. This is off by default and needs an administrator to turn it on at the host, with a public https address. Tokens are bound to the MCP server, PKCE is required, and the grantable scopes are api, docs and keys; administration is never grantable and an OAuth identity cannot create API keys. Each person sees and disconnects their apps on the Account page. Personal API keys keep working as before. Sign-in has not yet been verified against a specific hosted AI app.

Local file reads are limited

When the MCP server runs locally (stdio), a tool reads a file_path only inside allowed folders: your Documents and Downloads folders (and OneDrive Documents on Windows) plus the output folder by default, or the folders the operator lists instead. Hidden files and folders, symbolic links that lead outside, file types the receiving route does not accept, and files over the size limit (100 MiB, images 8 MiB) are refused before anything is read.

Works with#

• Documents: the document pipeline is what most of the API drives, upload, segment, translate, review, export.
• Keys: key-based projects and their change feed are the continuous-localization half of the API surface.
• Workflows: every run an agent launches executes a workflow, with the same steps and quality checks as a person-driven run.
• Engines: a step that names no engine falls back to the install's configured default.

Current limits#