Skip to content

Use LingoHub with AI agents

Three ways to give an AI agent access to LingoHub, and the rules it should follow.

An AI agent can work with LingoHub in three ways. Start with the first one that fits your setup.

Way Use it when What the agent gets
MCP tools Your agent supports MCP, such as Claude Code, Cursor or VS Code API V2 operations as tools, read-only by default
The CLI Your agent can run shell commands Every API V2 operation as a command with JSON output
The API and these docs The agent writes an integration for you The OpenAPI specs and every page of this site as Markdown

All three use an API key. Read Keys and permissions before you give an agent one.

The LingoHub CLI serves API V2 to MCP clients. Install the CLI, run lingohub login, then register the server with your client:

{
"mcpServers": {
"lingohub": { "command": "lingohub", "args": ["api", "mcp-serve"] }
}
}

In Claude Code, one command does the same:

Terminal window
claude mcp add lingohub -- lingohub api mcp-serve

By default the server offers a small set of read-only tools, so an agent can look around but not change anything. Offer more deliberately:

Terminal window
lingohub api mcp-serve --tag Projects --tag Imports # every operation of these groups
lingohub api mcp-serve --operation createImport # single operations
lingohub api mcp-serve --all # everything, including changes

lingohub api mcp-tools lists the tools a selection would offer, without starting a server. The tool names are the operation IDs of the API V2 reference.

An agent that can run commands needs no MCP setup. These commands are enough to start:

Terminal window
lingohub --json api call getApiKey # which key am I, and what may it do?
lingohub --json api call getWorkspace
lingohub api operations # every operation the CLI knows, offline

lingohub api call OPERATION calls any JSON operation by its operation ID; --json puts the API’s JSON on stdout. The CLI page shows how to pass parameters and how to import and export files.

The CLI is updated together with API V2, so an agent that uses it keeps working when the API changes during the beta.

An agent that writes code against the API needs the contract and the guides in a form it can read:

  • OpenAPI specs. API V2, API V1 and the CDN API, as JSON.
  • An index. /llms.txt lists every guide and recipe with a one-line description, and links an index of each API’s operations.
  • Every page as Markdown. Append .md to the URL of any page of this site, or request the page with Accept: text/markdown. The page menu Copy page copies the same Markdown.
  • Everything in one file. /llms-full.txt holds all guides and recipes.
  • The workflow guide. The Workflow and recovery guide is the compact version of the API V2 rules, written for agents. Every API build also serves it, next to its own spec.

/llms.txt starts with these rules. Put them into your agent’s instructions when it does not read that file itself:

  • Use API V2. It is in beta: check the deployed spec instead of relying on memory.
  • Take IDs from API responses. Never construct one.
  • Page through lists with cursor until has_more is false, with the same filter on every page.
  • Send an Idempotency-Key with every POST and retry with the same key. After an uncertain result, look at the resource before you send the request again.
  • Change existing objects with If-Match. On 412, read again and decide again; never overwrite blindly.
  • An accepted import or export is not a finished one. Poll the job and read its entries.
  • A segment is shared by every key that shows it. Check where it is used before you change it.
  • Never print or commit an API key.

An agent acts with the permissions of its key, so give it a key of its own with only what the task needs:

  • For work on your own computer, lingohub login stores a personal key that follows your permissions and expires after 90 days.
  • For an agent that runs unattended, create a key in the workspace settings, limit it to the stacks and permissions it needs, and set it as LINGOHUB_API_KEY. See API keys.
  • Start read-only. The MCP server’s default tools change nothing; add operations that write when the agent needs them.
  • LingoHub keeps a log of each key’s API V2 requests for a retention period: the API logs show what an agent called.