docs: rewrite MCP server pages for AEO and AI-client coverage

platform/faq.mdx

@@ -140,3 +140,19 @@ When some key seems unused, the CLI can remove it from the Tolgee Platform.
 To get started, Sign up for the [Tolgee Cloud](https://app.tolgee.io) or learn how to
 [self-host](/platform/self_hosting/running_with_docker#running-with-docker-compose-recommended) Tolgee,
 or read [integration docs](https://tolgee.io/integrations).
+
+### I'm getting a `429 Too Many Requests` error. What does it mean?
+
+You've hit the per-user rate limit for that API call. Slow down and retry. Rate limits refill on a sliding window, so the call will succeed again shortly without any action on your side.
+
+### I'm getting `Operation not permitted in read-only mode`. What does it mean?
+
+Your organization or Tolgee instance is in read-only mode, so write operations are rejected. Disable read-only mode in the organization settings, or stick to read-only operations until it's turned off.
+
+### I'm getting `Feature not enabled` for something like [Branching](/platform/branching/overview). What does it mean?
+
+The operation requires an Enterprise feature that your plan doesn't include. Enable the feature on your plan.
+
+### My self-hosted Tolgee instance is unreachable from my client. How do I debug it?
+
+Most often it's a network, firewall, or TLS misconfiguration. Confirm `curl -i https://your-tolgee.com/` returns a response from your Tolgee server, and verify the TLS certificate is valid. Remote clients (e.g. ChatGPT custom connectors, hosted IDEs) require a public HTTPS endpoint; local clients on the same machine can reach a local instance over `http://localhost`.

platform/integrations/mcp_server/about.mdx

@@ -1,15 +1,22 @@
 ---
 id: about
-title: Tolgee MCP Server Overview
+title: Tolgee MCP Server
 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?
+## What is the Tolgee MCP server?
 
-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 Tolgee MCP server is the [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. 
 
-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.
+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 HTTP.
+
+The server is maintained by the Tolgee team and listed in the [MCP Registry](https://registry.modelcontextprotocol.io/) as `io.github.tolgee/tolgee`.
+
+## 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. Authentication is always via the `X-API-Key` header.
 
 ## Available Roles
 
@@ -25,3 +32,21 @@ More roles (e.g. translator, project manager) are planned for future releases.
 
 1. Follow the [setup guide](/platform/integrations/mcp_server/setup) to connect your AI client to Tolgee.
 2. Check the [usage guide](/platform/integrations/mcp_server/usage) for example workflows and best practices.
+
+## 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. 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 |
+|---|---|---|---|
+| **Best for** | Conversational use from AI assistants | Scripts, CI sync/push/pull | Building your own apps & integrations |
+| **Where you use it** | 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 (use `tolgee --help`) | Low (read the OpenAPI spec) |
+| **Determinism** | Lower — natural language can be ambiguous | High | High |
+| **Bulk / batch ops** | ✔ | ✔ | ✔ |
+A common end-state of our users:
+
+- **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.

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
+- 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,25 +31,94 @@ 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: <your_PAK_or_PAT>"
 ```
 
-## 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": "<your_PAK_or_PAT>"
+      }
+    }
+  }
+}
+```
+
+## 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`.
+
+See [API keys and PAT tokens](/platform/account_settings/api_keys_and_pat_tokens) for how to create and manage each token type.
+
+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.
+
+## How do I verify the connection?
 
 After configuring your client, try a read-only command to confirm everything works:
 
 > **You:** List my Tolgee projects
 
 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 a few buckets: bad credentials, wrong token type, missing scopes, or the AI client not actually reaching the server. 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.
+
+For non-MCP-specific issues (rate limits, read-only mode, EE features, self-hosted unreachable, etc.) see the [platform FAQs](/platform/faq).
+
+**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`). |
+| `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. |
+| 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. |
+| 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 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": "<your_PAK_or_PAT>"
+       }
+     }
+   }
+ }
+```
+
+**Requirements for self-hosted:**
+- A Tolgee version that includes the MCP server (check the [changelog](https://github.com/tolgee/tolgee-platform/releases)).
+- HTTP(S) 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 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.

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 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 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
 
@@ -12,9 +31,9 @@ Once connected, you can interact with Tolgee in natural language. For example:
 > **You:** List all keys in the "homepage" namespace that contain "welcome"
 >
 > **AI:** Found 3 keys in namespace "homepage":
-> - `homepage.welcome_title` — "Welcome to our platform"
-> - `homepage.welcome_subtitle` — "Get started in minutes"
-> - `homepage.welcome_cta` — "Sign up free"
+> - `homepage.welcome_title` — "Welcome to our platform."
+> - `homepage.welcome_subtitle` — "Get started in minutes."
+> - `homepage.welcome_cta` — "Sign up free."
 
 > **You:** Translate these keys to German and French using machine translation
 >