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.
MCP tools
Section titled “MCP tools”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:
claude mcp add lingohub -- lingohub api mcp-serveBy default the server offers a small set of read-only tools, so an agent can look around but not change anything. Offer more deliberately:
lingohub api mcp-serve --tag Projects --tag Imports # every operation of these groupslingohub api mcp-serve --operation createImport # single operationslingohub api mcp-serve --all # everything, including changeslingohub 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.
The CLI
Section titled “The CLI”An agent that can run commands needs no MCP setup. These commands are enough to start:
lingohub --json api call getApiKey # which key am I, and what may it do?lingohub --json api call getWorkspacelingohub api operations # every operation the CLI knows, offlinelingohub 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.
The API and these docs
Section titled “The API and these docs”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.txtlists every guide and recipe with a one-line description, and links an index of each API’s operations. - Every page as Markdown. Append
.mdto the URL of any page of this site, or request the page withAccept: text/markdown. The page menu Copy page copies the same Markdown. - Everything in one file.
/llms-full.txtholds 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.
Rules to give your agent
Section titled “Rules to give your agent”/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
cursoruntilhas_moreis false, with the samefilteron every page. - Send an
Idempotency-Keywith everyPOSTand 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. On412, 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.
Keys and permissions
Section titled “Keys and permissions”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 loginstores 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.