From 6e6ee9490b7f0adfd2afb6728c7497db1b919c2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Barush=20Urbanov=C3=A1?= Date: Fri, 15 May 2026 19:13:12 +0200 Subject: [PATCH 1/2] docs: rewrite MCP server pages for AEO and AI-client coverage docs: rewrite MCP server pages for AEO and AI-client coverage - Add quotable TL;DR intros to about, setup and usage pages - Replace generic headings with question-led sections (what / how / which) - Document Claude Desktop, Claude Code and Cursor configs with copy-paste blocks - List all 20 tools grouped by category (keys, translations, languages, tags, namespaces, branches, batch/MT, big meta, projects) - Add Tolgee MCP vs CLI vs REST API comparison - Add auth deep-dive (PAK vs PAT, X-API-Key, error codes) - Add self-hosted setup and Redis session-persistence notes - Add permissions section (scopes, read-only mode, EE feature gating) - Add troubleshooting table with common errors and diagnostic prompts --- platform/integrations/mcp_server/about.mdx | 49 +++++++++- platform/integrations/mcp_server/setup.mdx | 103 +++++++++++++++++++-- platform/integrations/mcp_server/usage.mdx | 19 ++++ 3 files changed, 158 insertions(+), 13 deletions(-) diff --git a/platform/integrations/mcp_server/about.mdx b/platform/integrations/mcp_server/about.mdx index 7f0318dde..503f40bb4 100644 --- a/platform/integrations/mcp_server/about.mdx +++ b/platform/integrations/mcp_server/about.mdx @@ -1,15 +1,58 @@ --- id: about -title: Tolgee MCP Server Overview +title: Tolgee MCP Server — Official Localization MCP for AI sidebar_label: About description: 'Connect AI assistants like Claude, Cursor, or ChatGPT to Tolgee using the Model Context Protocol (MCP) server.' --- +The Tolgee MCP Server brings the full power of Tolgee into your AI coding assistant, letting you manage translations without ever leaving your editor. Connect Claude Code, Cursor, or any MCP-compatible AI assistant to your Tolgee project and start managing localization tasks conversationally. ## What is MCP? -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. +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that allows AI assistants to interact with external tools and services. MCP servers let you manage your data directly from AI-powered tools like Claude Desktop, Cursor, Windsurf, ChatGPT, and others. -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. +## What is the Tolgee MCP server? + +The Tolgee MCP server is the official [Model Context Protocol](https://modelcontextprotocol.io/) endpoint built into the Tolgee platform. It lets AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT, and any other MCP-compatible client) manage your Tolgee localization projects through natural language. It is hosted at `https://app.tolgee.io/mcp/developer` for Tolgee Cloud and is available on every self-hosted Tolgee instance. No proxy, no separate process. Your AI client talks to Tolgee directly over HTTPS. + +The server is **official**, maintained by the Tolgee team, and listed in the [Official MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.tolgee/tolgee`. + +## How does the Tolgee MCP server compare to the Tolgee CLI and REST API? + +All three talk to the same underlying Tolgee API but target different workflows. The Tolgee **MCP server** is for natural-language use from inside an AI assistant — no client library, no script, you just ask. The Tolgee [CLI](/tolgee-cli/introduction) is for scripted, repeatable operations such as `push` and `pull` in CI pipelines. The Tolgee [REST API](/api) is for building your own integrations, dashboards, or in-product features. They are complementary, not alternatives, most teams end up using two or three. + +| | Tolgee MCP server | Tolgee CLI | Tolgee REST API | +|---|---|---|---| +| **Best for** | Conversational use from AI assistants | Scripts, CI sync/push/pull | Building your own apps & integrations | +| **Surface** | Claude, Cursor, ChatGPT, Windsurf… | Terminal | Your code (any language) | +| **Auth** | PAK or PAT via `X-API-Key` | PAK or PAT | PAK or PAT | +| **Discoverability** | High — AI lists tools and prompts for missing params | Medium — `tolgee --help` | Low — read the OpenAPI spec | +| **Determinism** | Lower — natural language can be ambiguous | High | High | +| **Bulk / batch ops** | ✔ `machine_translate`, etc. | ✔ | ✔ | +| **Latency per call** | One HTTP round-trip | One HTTP round-trip | One HTTP round-trip | +| **Sandboxed by client** | ✔ (client shows confirmation for destructive ops) | ❌ runs whatever you type | ❌ runs whatever you call | + +A common end-state for a Tolgee team: + +- **MCP server** — day-to-day exploratory work and one-off fixes from inside Claude or Cursor. +- **CLI** — committed sync between repo and Tolgee in CI (e.g. `tolgee push` on merge to `main`). +- **REST API** — in-app translation lookup, custom dashboards, or webhooks. + +## Which MCP clients are supported? + +The Tolgee MCP server uses the standard **streamable-HTTP** MCP transport, so it works with any MCP-compatible client that supports remote HTTP servers and custom request headers. Officially tested clients are **Claude Desktop**, **Claude Code**, **Cursor**, **Windsurf**, and **ChatGPT** (via custom MCP connectors). Authentication is always via the `X-API-Key` header. Clients that only support the local stdio transport are not supported directly, but they can connect through an HTTP-to-stdio bridge if needed. + +| Client | Status | Transport | +|---|---|---| +| Claude Desktop | Supported | HTTP | +| Claude Code | Supported | HTTP | +| Cursor | Supported | HTTP | +| Windsurf | Supported | HTTP | +| ChatGPT (custom connector) | Supported | HTTP | +| VS Code MCP | Supported | HTTP | +| Zed | Supported | HTTP | +| Any stdio-only client | Use an HTTP bridge | — | + +If your client supports MCP but is not listed here, it almost certainly works. [File an issue](https://github.com/tolgee/tolgee-platform/issues) if it doesn't and we'll look into it. ## Available Roles diff --git a/platform/integrations/mcp_server/setup.mdx b/platform/integrations/mcp_server/setup.mdx index 39b9114b5..8dfd9c78d 100644 --- a/platform/integrations/mcp_server/setup.mdx +++ b/platform/integrations/mcp_server/setup.mdx @@ -5,19 +5,17 @@ sidebar_label: Setup description: 'Learn how to connect your AI assistant to Tolgee via the MCP server.' --- +To set up the Tolgee MCP server, add an HTTP MCP entry to your AI client's configuration pointing at `https://app.tolgee.io/mcp/developer` (or your self-hosted Tolgee URL), and authenticate with a Tolgee **Project API Key (PAK)** or **Personal Access Token (PAT)** in the `X-API-Key` header. This page covers config snippets for Claude Desktop, Claude Code, Cursor, and any other MCP-compatible client, plus how to verify the connection works. + ## Prerequisites - A Tolgee account (cloud or self-hosted) - 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) - An MCP-compatible AI client -:::info -**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. -::: +## How do I connect Tolgee to Claude Desktop / Claude Code? -## Claude Desktop / Claude Code - -Add the following to your MCP configuration: +To connect Tolgee to **Claude Desktop**, add the Tolgee MCP server to your `claude_desktop_config.json` using the HTTP transport, then restart Claude Desktop. Authentication uses your Tolgee **Project API Key (PAK)** or **Personal Access Token (PAT)**, passed in the `X-API-Key` header. The server URL is `https://app.tolgee.io/mcp/developer` for Tolgee Cloud. ```json { @@ -33,18 +31,57 @@ Add the following to your MCP configuration: } ``` -Or using the CLI: +If you use **Claude Code**, add the same server with one command: ```bash claude mcp add --transport http tolgee https://app.tolgee.io/mcp/developer \ --header "X-API-Key: " ``` -## Cursor -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. +## How do I connect Tolgee to Cursor? + +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. After saving, Cursor shows a green "connected" indicator next to the Tolgee server in the MCP settings panel. -## Verifying the Connection +If you prefer file-based config, add this block to `~/.cursor/mcp.json`: + +```json +{ + "mcpServers": { + "tolgee": { + "type": "http", + "url": "https://app.tolgee.io/mcp/developer", + "headers": { + "X-API-Key": "" + } + } + } +} +``` + +## How do I authenticate the Tolgee MCP server? + +The Tolgee MCP server authenticates via the **`X-API-Key`** HTTP header on every request, using either a Tolgee **Project API Key (PAK)** or a **Personal Access Token (PAT)**. A PAK is scoped to a single project and avoids passing `projectId` on every call. A PAT inherits your full user permissions across every project you can access. Use a PAK for day-to-day work on one project; use a PAT when you need to switch projects or call global tools like `list_projects` or `create_project`. + +| | Project API Key (PAK) | Personal Access Token (PAT) | +|---|---|---| +| Scope | A single project | All projects you can access | +| `projectId` in tool calls | Not needed — resolved from the PAK | Required for project-scoped tools | +| Permissions | Per-key scopes (configurable) | Inherits your user role | +| Global tools (`list_projects`, `create_project`) | Not available | Available | +| Best for | Daily work on one project | Cross-project work, admin tasks | +| Where to create | **Project → Integrate → API keys** | **User settings → Personal access tokens** | + +Some tools are restricted to one token type. If you use the wrong one, the Tolgee MCP server returns `PAK_ACCESS_NOT_ALLOWED` or `PAT_ACCESS_NOT_ALLOWED`. Switch tokens and retry. + +:::info +- Treat the token like a database password — anyone holding it gets the same scopes the token has. +- Prefer per-agent tokens. If you have an automated AI bot, give it a dedicated PAK with the minimum scopes, separate from your personal one. +- Rotate tokens on a schedule. Revoke a token immediately if a config file containing it is shared or committed. +- Use your MCP client's secret store if it has one, rather than committing the token to a config file. +::: + +## How do I verify the connection? After configuring your client, try a read-only command to confirm everything works: @@ -52,6 +89,52 @@ After configuring your client, try a read-only command to confirm everything wor If the connection is successful, the AI assistant will return a list of projects accessible with your token. +If it returns an error, double-check that the API key is valid and has access to at least one project. + :::info For self-hosted instances, replace `https://app.tolgee.io` with your own Tolgee server URL. ::: + +## How do I troubleshoot the Tolgee MCP server? + +Most Tolgee MCP server problems fall into five buckets: bad credentials, wrong token type, missing scopes, the AI client not actually reaching the server, or a self-hosted instance unreachable from the client's network. Start every diagnosis by asking your AI assistant *"List my Tolgee projects"*. This calls a read-only global tool and surfaces auth and connection problems without changing any data. The error returned tells you which layer failed. + +**Common errors and fixes:** + +| Symptom | Likely cause | Fix | +|---|---|---| +| `401 Unauthorized` | `X-API-Key` header missing, token invalid, or token revoked | Re-check the header in your MCP client config. Regenerate the token in Tolgee if needed. | +| `PAK_ACCESS_NOT_ALLOWED` | Tool is PAT-only, you used a PAK | Use a PAT for this specific tool | +| `PAT_ACCESS_NOT_ALLOWED` | Tool is PAK-only, you used a PAT | Use a PAK for this specific tool | +| `403 Permission denied` on a scope | The PAK lacks the required scope | Regenerate the PAK with the missing scope (e.g. add `translations.edit`) | +| `Operation not permitted in read-only mode` | Organization or instance is in read-only mode | Disable read-only mode in org settings, or stick to read tools | +| `Feature not enabled` (e.g. Branching) | Tool requires an EE feature your plan doesn't include | Enable the feature on your plan, or use the equivalent REST API call from a different surface | +| `Project not selected` | Using a PAT on a project-scoped tool without supplying `projectId` | Mention the project explicitly in the prompt, or switch to a PAK | +| `429 Too Many Requests` | Hit the per-user rate limit for that tool | Slow down; rate limits refill on a sliding window | +| AI never actually calls Tolgee tools | MCP server not connected in the client | Check the connection indicator (Claude: green check; Cursor: green dot in Settings → MCP). Restart the client after editing config. | +| Self-hosted instance unreachable | Network, firewall, or HTTPS misconfiguration | Confirm `curl -i https://your-tolgee.com/mcp/developer` returns a response from the MCP transport; verify the TLS certificate is valid | +| Session lost mid-conversation (self-hosted) | Redis not configured + request hit a different load-balanced node | Configure Redis in your Tolgee deployment so MCP sessions persist across nodes | + +## Can I use the Tolgee MCP server with self-hosted Tolgee? + +Yes, the Tolgee MCP server is built into the Tolgee platform itself, so every self-hosted Tolgee instance exposes it automatically at `/mcp/developer`. To connect, replace the Tolgee Cloud URL in your MCP client config with your own server's base URL. There is no extra deployment, your self-hosted instance just needs to be reachable over HTTPS from wherever your AI client runs. + +```diff + { + "mcpServers": { + "tolgee": { + "type": "http", +- "url": "https://app.tolgee.io/mcp/developer", ++ "url": "https://tolgee.your-company.com/mcp/developer", + "headers": { + "X-API-Key": "" + } + } + } + } +``` + +**Requirements for self-hosted:** +- A Tolgee version that includes the MCP server (check the [changelog](https://github.com/tolgee/tolgee-platform/releases)). +- HTTPS reachable from the network your AI client runs in. Local Tolgee on `http://localhost:8200` works for desktop clients on the same machine; remote clients (ChatGPT custom connector, hosted Cursor, etc.) require a public HTTPS endpoint. +- **Redis recommended for production.** MCP session state is persisted to Redis when configured. Without Redis, sessions live only in the JVM memory of the node that handled the handshake. Load-balanced deployments without Redis will lose sessions on subsequent requests. diff --git a/platform/integrations/mcp_server/usage.mdx b/platform/integrations/mcp_server/usage.mdx index 1d42c0ce2..7ef4784fc 100644 --- a/platform/integrations/mcp_server/usage.mdx +++ b/platform/integrations/mcp_server/usage.mdx @@ -4,6 +4,25 @@ title: Usage Tolgee MCP Server sidebar_label: Usage description: 'Examples and best practices for using Tolgee MCP Server with AI assistants.' --- +Once the Tolgee MCP server is connected, you manage your localization project by asking your AI assistant in natural language: list and search translation keys, get and set translations, trigger batch machine translation, and manage languages, tags, namespaces and branches. This page shows example prompts you can paste into Claude, Cursor, Windsurf, or ChatGPT, plus best practices for keeping your AI-driven localization workflow safe, fast, and accurate. + +## What can I do with the Tolgee MCP server? + +The Tolgee MCP server exposes 20 tools covering the full localization workflow: list, search, create, update and delete translation keys; get and set translations; manage languages, tags, namespaces and branches; run batch machine-translation jobs; store context for better MT quality; and query project statistics. In short, anything you'd normally do in the Tolgee UI can be done from your AI assistant in natural language. + +**Tools by category:** + +| Category | Tools | +|---|---| +| Projects | `list_projects`, `create_project`, `get_project_language_statistics` | +| Keys | `list_keys`, `search_keys`, `get_key`, `create_keys`, `update_key`, `delete_keys` | +| Translations | `get_translations`, `set_translation` | +| Languages | `list_languages`, `create_language` | +| Tags | `list_tags`, `tag_keys` | +| Namespaces | `list_namespaces` | +| Branches | `list_branches`, `create_branch`, `delete_branch` | +| Batch / Machine translation | `machine_translate`, `get_batch_job_status` | +| Context for MT | `store_big_meta` | ## Example Workflow From b68c2813c49553a293eb41d5ee702d734e5f648d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Barush=20Urbanov=C3=A1?= Date: Sun, 17 May 2026 20:03:40 +0200 Subject: [PATCH 2/2] broken link fix --- platform/integrations/mcp_server/about.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/platform/integrations/mcp_server/about.mdx b/platform/integrations/mcp_server/about.mdx index 503f40bb4..54cb2ab74 100644 --- a/platform/integrations/mcp_server/about.mdx +++ b/platform/integrations/mcp_server/about.mdx @@ -18,7 +18,7 @@ The server is **official**, maintained by the Tolgee team, and listed in the [Of ## How does the Tolgee MCP server compare to the Tolgee CLI and REST API? -All three talk to the same underlying Tolgee API but target different workflows. The Tolgee **MCP server** is for natural-language use from inside an AI assistant — no client library, no script, you just ask. The Tolgee [CLI](/tolgee-cli/introduction) is for scripted, repeatable operations such as `push` and `pull` in CI pipelines. The Tolgee [REST API](/api) is for building your own integrations, dashboards, or in-product features. They are complementary, not alternatives, most teams end up using two or three. +All three talk to the same underlying Tolgee API but target different workflows. The Tolgee **MCP server** is for natural-language use from inside an AI assistant — no client library, no script, you just ask. The Tolgee [CLI](/tolgee-cli) is for scripted, repeatable operations such as `push` and `pull` in CI pipelines. The Tolgee [REST API](/api) is for building your own integrations, dashboards, or in-product features. They are complementary, not alternatives, most teams end up using two or three. | | Tolgee MCP server | Tolgee CLI | Tolgee REST API | |---|---|---|---|