Skip to content

Commit 109f830

Browse files
bdshadowclaude
bdshadow
and
claude
committed
docs: add MCP server documentation
Add documentation for the Tolgee MCP server integration split into three pages (about, setup, usage) covering what MCP is, prerequisites, available roles, client configuration, example workflows, and best practices. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent b635d0d commit 109f830

File tree

5 files changed

+123
-1
lines changed

5 files changed

+123
-1
lines changed

‎platform/integrations/about_integrations.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,4 +24,4 @@ Currently, Tolgee has integrations for **all major JS frameworks** such as [Reac
2424
For mobile native apps, see our [mobile docs](/android-sdk).
2525

2626
**Other integrations:** [Figma](/platform/integrations/figma_plugin/setup), [Unreal](/platform/integrations/unreal_plugin/setup),
27-
[CLI](https://tolgee.io/tolgee-cli), [REST API](/api), [Slack](/platform/integrations/slack_integration/setup)
27+
[CLI](https://tolgee.io/tolgee-cli), [REST API](/api), [Slack](/platform/integrations/slack_integration/setup),[MCP Server](/platform/integrations/mcp_server/about)

‎platform/integrations/mcp_server/about.mdx‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
id: about
3+
title: Tolgee MCP Server Overview
4+
sidebar_label: About
5+
description: 'Connect AI assistants like Claude, Cursor, or ChatGPT to Tolgee using the Model Context Protocol (MCP) server.'
6+
---
7+
8+
## What is MCP?
9+
10+
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI assistants to interact with external tools and services. Tolgee's MCP server lets you manage your localization projects directly from AI-powered tools like Claude Desktop, Cursor, Windsurf, ChatGPT, and others.
11+
12+
Instead of switching between your IDE and the Tolgee UI, you can ask your AI assistant to list keys, update translations, trigger machine translation, and more — all through natural language.
13+
14+
## Available Roles
15+
16+
The MCP server currently exposes a single role-based endpoint:
17+
18+
| Role | Endpoint | Description |
19+
|------|----------|-------------|
20+
| **Developer** | `/mcp/developer` | Full access to keys, translations, languages, tags, namespaces, branches, and batch operations. |
21+
22+
More roles (e.g. translator, project manager) are planned for future releases.
23+
24+
## How to Get Started
25+
26+
1. Follow the [setup guide](/platform/integrations/mcp_server/setup) to connect your AI client to Tolgee.
27+
2. Check the [usage guide](/platform/integrations/mcp_server/usage) for example workflows and best practices.

‎platform/integrations/mcp_server/setup.mdx‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
---
2+
id: setup
3+
title: Setup Tolgee MCP Server
4+
sidebar_label: Setup
5+
description: 'Learn how to connect your AI assistant to Tolgee via the MCP server.'
6+
---
7+
8+
## Prerequisites
9+
10+
- A Tolgee account (cloud or self-hosted)
11+
- A **Project API key (PAK)** or a **Personal Access Token (PAT)** — see [API keys and PAT tokens](/platform/account_settings/api_keys_and_pat_tokens)
12+
- An MCP-compatible AI client
13+
14+
:::info
15+
**PAK vs PAT** — A Project API key is scoped to a single project, so you don't need to specify `projectId` in every request. A Personal Access Token gives access to all projects you have permissions for, but you must pass `projectId` explicitly when calling project-scoped tools.
16+
:::
17+
18+
## Claude Desktop / Claude Code
19+
20+
Add the following to your MCP configuration:
21+
22+
```json
23+
{
24+
"mcpServers": {
25+
"tolgee": {
26+
"type": "http",
27+
"url": "https://app.tolgee.io/mcp/developer",
28+
"headers": {
29+
"X-API-Key": "<your_PAK_or_PAT>"
30+
}
31+
}
32+
}
33+
}
34+
```
35+
36+
Or using the CLI:
37+
38+
```bash
39+
claude mcp add --transport http tolgee https://app.tolgee.io/mcp/developer \
40+
--header "X-API-Key: <your_PAK_or_PAT>"
41+
```
42+
43+
## Cursor
44+
45+
Open **Settings > MCP** and add a new server with the HTTP transport pointing to `https://app.tolgee.io/mcp/developer`. Pass your token via the `X-API-Key` header.
46+
47+
## Verifying the Connection
48+
49+
After configuring your client, try a read-only command to confirm everything works:
50+
51+
> **You:** List my Tolgee projects
52+
53+
If the connection is successful, the AI assistant will return a list of projects accessible with your token.
54+
55+
:::info
56+
For self-hosted instances, replace `https://app.tolgee.io` with your own Tolgee server URL.
57+
:::

‎platform/integrations/mcp_server/usage.mdx‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
id: usage
3+
title: Usage Tolgee MCP Server
4+
sidebar_label: Usage
5+
description: 'Examples and best practices for using Tolgee MCP Server with AI assistants.'
6+
---
7+
8+
## Example Workflow
9+
10+
Once connected, you can interact with Tolgee in natural language. For example:
11+
12+
> **You:** List all keys in the "homepage" namespace that contain "welcome"
13+
>
14+
> **AI:** Found 3 keys in namespace "homepage":
15+
> - `homepage.welcome_title` — "Welcome to our platform"
16+
> - `homepage.welcome_subtitle` — "Get started in minutes"
17+
> - `homepage.welcome_cta` — "Sign up free"
18+
19+
> **You:** Translate these keys to German and French using machine translation
20+
>
21+
> **AI:** Started machine translation batch job. Job ID: 42. Checking status... completed. All 3 keys have been translated to German (de) and French (fr).
22+
23+
## Best Practices
24+
25+
- **Start with read-only commands** — Use `list_keys`, `get_translations`, or `list_projects` first to verify that your connection works before making changes.
26+
- **Use a Project API key when working on a single project** — This avoids having to specify `projectId` with every request and limits the blast radius of accidental changes.
27+
- **Be careful with destructive operations** — Tools like `delete_keys` and `delete_branch` are irreversible. AI assistants are instructed to confirm with you before executing them, but always double-check.
28+
- **Keep tokens secure** — Store your API keys in environment variables or a secrets manager. Don't commit them to version control. Use the minimum required scopes and rotate tokens regularly.
29+
- **Leverage Big Meta for better MT quality** — If you're using machine translation, store key relationships with `store_big_meta` so Tolgee can use translations of related keys as context.

‎sidebarPlatform.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -127,6 +127,15 @@ module.exports = {
127127
'integrations/unreal_plugin/usage',
128128
],
129129
},
130+
{
131+
label: 'MCP Server',
132+
type: 'category',
133+
items: [
134+
'integrations/mcp_server/about',
135+
'integrations/mcp_server/setup',
136+
'integrations/mcp_server/usage',
137+
],
138+
},
130139
'integrations/other_integrations',
131140
],
132141
},

0 commit comments

Comments
 (0)