Version: 3.x.x

Setup Tolgee 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
An MCP-compatible AI client

How do I connect Tolgee to Claude Desktop / Claude Code?

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.

{
  "mcpServers": {
    "tolgee": {
      "type": "http",
      "url": "https://app.tolgee.io/mcp/developer",
      "headers": {
        "X-API-Key": "<your_PAK_or_PAT>"
      }
    }
  }
}

If you use Claude Code, add the same server with one command:

claude mcp add --transport http tolgee https://app.tolgee.io/mcp/developer \
  --header "X-API-Key: <your_PAK_or_PAT>"

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.

If you prefer file-based config, add this block to ~/.cursor/mcp.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.

	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:

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 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.

 {
   "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 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.

Prerequisites​

How do I connect Tolgee to Claude Desktop / Claude Code?​

How do I connect Tolgee to Cursor?​

How do I authenticate the Tolgee MCP server?​

How do I verify the connection?​

How do I troubleshoot the Tolgee MCP server?​

Can I use the Tolgee MCP server with self-hosted Tolgee?​