MCP for better development with AI agents #3620

Problem

The MCP server we ship today works but has rough edges that limit how well AI coding agents (Claude, Cursor, etc.) can integrate Tolgee into a real development workflow. These issues accumulated as we iterated on individual features; this pitch bundles the fixes and the follow-up work into one coherent direction.

Context: #3574.

Solution

1. create_keys accepts full key metadata in one call

Auto-translation runs immediately after key creation and uses description, comments, codeReferences, and custom as context. Today an agent can only pass tags and description at creation time — everything else needs a follow-up call, by which point translations are already generated without that context.

create_keys should accept the full KeyMeta surface (including screenshots, see #3) in a single call so the agent can create everything in one shot before auto-translation fires.

2. Signed upload URL for images (replace base64)

The upload_image tool proposed in #3574 accepts base64. That would bloat tokens ~33%, be slow for non-trivial images, and push the whole image through the LLM tool call.

Before that ships, mark upload_image as not recommended and add a tool that returns a single-use upload URL. The client (Claude or any other tool) uploads the image directly to that URL out-of-band. The URL is single-use, so it doesn't need an API key.

Lifetime: 30 minutes by default, configurable via a property.

3. Dedicated aiContext field on keys

description is for translators. Today AI coding tools have nowhere clean to put their own context (code positions, usage hints, instructions for future edits) — it ends up polluting description or hiding in unstructured custom.

Add a first-class aiContext field on keys that AI tools can read/write. Keeps concerns separated: translator-facing text stays in description, agent-facing context lives in aiContext.

4. Public Claude skill + walkthrough video

Publish a Claude Code skill and a short walkthrough video showing the end-to-end Tolgee + Claude workflow. Discoverability is the biggest gap once the API shape settles.

No-gos

• Versioning aiContext — treat it as opaque; the AI tool owns the shape inside it.
• Redesigning the existing MCP tool surface — this is additive, not a rewrite.

Appetite

1 week