Installation

Who is this for? Complete setup reference for all installation modes.

When should I read this? When you need the full picture: plugins, offline, or the optional MCP modes (HTTP, STDIO) and their environment variables. For the fastest path, see Quick Start.

[!WARNING] You must receive prior approval from your manager and company to use Rosetta.

[!WARNING] Use Sonnet 5 medium, GPT-5.4-medium, gemini-3.1-pro or newer models. Avoid Auto model selection.

[!NOTE] There will be conflict if you have similar plugins installed: JUXT, Superpowers, GSD, AI-DevKit. Use the ones you have the most experience with.

Choose Your Mode

Step 1: Install

Pick one mode and follow its section. Start with Plugin unless you have a specific reason to use MCP (HTTP or STDIO) — see MCPs Installation for when that applies.

Plugin-Based Installation

Rosetta publishes plugins for supported IDEs. Each plugin installs the full Rosetta instruction set locally. Every plugin supports two installation methods:

• Marketplace — managed install from a plugin marketplace. Easier; preferred when available.
• Standalone — manual zip extraction into your repo. For agents without a marketplace path, or environments that block external marketplaces.

Read more about plugin contents and capabilities in Plugins.

claude plugin marketplace add griddynamics/rosetta
claude plugin install rosetta@rosetta

HTTP Transport (MCP, optional)

Use this only if your IDE has no Rosetta plugin, or you specifically need centrally-managed instructions — see MCPs Installation.

[!NOTE] Rosetta is designed to never use or see data or IP. Instead it uses inversion of control, by providing a “menu” to AI coding agents.

[!NOTE] The endpoint below (mcp.rosetta.griddynamics.net) is a public hosted instance for evaluation only — do not point production or sensitive repositories at it. Production use of MCP means deploying your own MCP server and RAGFlow inside your organization’s perimeter — see Deployment Guide.

Rosetta uses HTTP MCP transport with OAuth.

1. Pick your IDE and add the configuration.
2. Authenticate to MCP using GitHub account according to IDE.

{
  "mcpServers": {
    "Rosetta": {
      "url": "https://mcp.rosetta.griddynamics.net/mcp"
    }
  }
}

claude mcp add --transport http Rosetta https://mcp.rosetta.griddynamics.net/mcp

codex mcp add Rosetta --url https://mcp.rosetta.griddynamics.net/mcp
codex mcp login Rosetta

{
  "servers": {
    "Rosetta": {
      "url": "https://mcp.rosetta.griddynamics.net/mcp"
    }
  }
}

{
  "servers": {
    "Rosetta": {
      "url": "https://mcp.rosetta.griddynamics.net/mcp"
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "url": "https://mcp.rosetta.griddynamics.net/mcp"
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "url": "https://mcp.rosetta.griddynamics.net/mcp"
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "serverUrl": "https://mcp.rosetta.griddynamics.net/mcp"
    }
  }
}

{
  "mcp": {
    "Rosetta": {
      "type": "http",
      "url": "https://mcp.rosetta.griddynamics.net/mcp",
      "enabled": true
    }
  }
}

Any MCP client that supports HTTP transport can connect using the endpoint URL. Complete the OAuth flow when prompted.

STDIO Transport (MCP, optional)

STDIO runs Rosetta MCP as a local process. Your IDE launches it and communicates over stdin/stdout.

Get Your API Key

1. Open Rosetta Server (RAGFlow)
2. Create an account or sign in
3. Generate an API key from your profile

Join Your Team’s Datasets

Your team lead shares Instructions and Project datasets. You must accept the invite before you can see them. Check your Rosetta Server inbox for pending invitations.

Configure Your IDE

Required environment variables:

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["rosetta-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "[RAGFlow production server URL]",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

claude mcp add --transport stdio Rosetta \
  --env ROSETTA_SERVER_URL=[RAGFlow production server URL] \
  --env ROSETTA_API_KEY=your-api-key \
  --env ROSETTA_USER_EMAIL=you@example.com \
  -- uvx rosetta-mcp@latest

codex mcp add Rosetta \
  --env ROSETTA_SERVER_URL=[RAGFlow production server URL] \
  --env ROSETTA_API_KEY=your-api-key \
  --env ROSETTA_USER_EMAIL=you@example.com \
  -- uvx rosetta-mcp@latest

{
  "servers": {
    "Rosetta": {
      "type": "stdio",
      "command": "uvx",
      "args": ["rosetta-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "[RAGFlow production server URL]",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "servers": {
    "Rosetta": {
      "type": "stdio",
      "command": "uvx",
      "args": ["rosetta-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "[RAGFlow production server URL]",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["rosetta-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "[RAGFlow production server URL]",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["rosetta-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "[RAGFlow production server URL]",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["rosetta-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "[RAGFlow production server URL]",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcp": {
    "Rosetta": {
      "type": "local",
      "command": ["uvx", "rosetta-mcp@latest"],
      "enabled": true,
      "env": {
        "ROSETTA_SERVER_URL": "[RAGFlow production server URL]",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

Environment Variables Reference

Required for STDIO transport. Optional otherwise.

Do not set VERSION. It uses a server-controlled default for managed upgrades. See MCP Architecture — Tradeoffs for rationale.

Offline Installation (No MCP)

Very rarely needed today — plugins cover the same “no server, no live connection” need for virtually everyone. Mainly used when developing Rosetta itself, or in the rare case a plugin genuinely isn’t available for your IDE.

1. Disable or remove Rosetta MCP from your IDE configuration
2. Download instructions.zip from the latest release
3. Extract to instructions/ in your repository or workspace
4. Copy the contents of local-files-mode.md into your IDE’s instruction file (keep frontmatter!):

Step 2: Add Bootstrap Rule (HTTP and STDIO modes ONLY)

Applies to HTTP and STDIO modes.

Skip if using Plugin or Offline installation.

Download mcp-files-mode.md and add it to your IDE’s instruction file (keep entire contents, including YAML frontmatter):

[!NOTE] Some tools (Cline, Kilo) do not read MCP server prompts. For these, mcp-files-mode.md is always required.

Step 3: Verify

Applies to all installation modes. Ask the agent:

What can you do, Rosetta?

The agent should follow Rosetta’s prompts and list its workflows:

• Plugin or Offline: it loads the Rosetta instructions bundled locally — no MCP call.
• HTTP or STDIO (MCP): it retrieves agents, guardrails, and instructions over Rosetta MCP.

Common Issues (MCP)

• OAuth prompt does not appear: restart your IDE and retry the connection. Read more in Troubleshooting — Connection & Authentication.
• Agent ignores Rosetta tools: confirm the MCP server shows as connected in your IDE’s MCP settings. Add a bootstrap rule if the agent still skips Rosetta. Read more in Troubleshooting — Agent Not Using Rosetta.
• Slow or empty responses: check your network can reach your Rosetta MCP host. See TROUBLESHOOTING.md.

Step 4: Initialize Repository

Run once per repository after installation:

Greenfield (new repository):

Initialize this repository using the respective Rosetta workflow, this is a new repository, target tech stack: ..., target architecture: ..., business context: ...

Brownfield (existing repository):

Ask the agent to initialize the repository:

Initialize this repository using the respective Rosetta workflow

Optionally, add details to that same request. If your workspace contains multiple repositories:

Initialize this repository using the respective Rosetta workflow, this is a composite workspace

To tell the agent where dead code or existing specs live:

Initialize this repository using the respective Rosetta workflow, dead code is in <path>, existing specs are in <path>

The agent runs an eight-phase workflow (see Usage Guide — Init Workspace for details):

1. Context — detect workspace mode and build file inventory
2. Shells — generate IDE/agent shell files from KB schemas
3. Discovery — produce TECHSTACK.md, CODEMAP.md, DEPENDENCIES.md
4. Rules (optional) — configure local agent rules
5. Patterns — extract recurring coding and architectural patterns
6. Documentation — create CONTEXT.md, ARCHITECTURE.md, IMPLEMENTATION.md, ASSUMPTIONS.md
7. Questions — clarifying questions about gaps and assumptions
8. Verification — completeness check and catch-up for missed artifacts

[!NOTE] Composite workspaces: init each repository separately, then init at the workspace level with “This is composite workspace” appended. Dead code or existing specs: mention their location in the prompt to save time.

Workspace Files Created

After initialization, Rosetta maintains these files in your repository. Read more about their purpose in Architecture — Workspace Files.

Committed to SCM:

• gain.json - SDLC setup and Rosetta file locations
• docs/CONTEXT.md - business context (no technical details)
• docs/ARCHITECTURE.md - architecture and technical requirements
• docs/TECHSTACK.md - tech stack of all modules
• docs/DEPENDENCIES.md - dependencies of all modules
• docs/CODEMAP.md - code map of workspace
• docs/TODO.md - improvements, feature requests, TODOs (created when needed)
• docs/ASSUMPTIONS.md - assumptions and unknowns (created when needed)
• docs/REQUIREMENTS/* - original requirements with INDEX.md (optional)
• docs/PATTERNS/* - coding and architectural patterns with INDEX.md (optional)
• agents/IMPLEMENTATION.md - current implementation state (the only changelog)
• agents/MEMORY.md - root causes of errors and lessons learned
• plans/<FEATURE>/<FEATURE>-PLAN.md - execution plans
• plans/<FEATURE>/<FEATURE>-SPECS.md - tech specs
• refsrc/INDEX.md - index of reference documentation (only refsrc file committed)

Excluded from SCM:

• refsrc/* (except INDEX.md) - reference knowledge files
• agents/TEMP/<FEATURE> - temporary implementation files

Upgrading

• Plugins (marketplace): Usually upgrade automatically. For Claude Code:

  claude plugin marketplace update rosetta
  claude plugin update rosetta@rosetta
  

• Plugins (standalone): Redownload the zip from releases and replace the extracted files (install again).
• HTTP: No action needed. Server-side upgrades apply automatically.
• STDIO: uvx rosetta-mcp@latest always pulls the newest published version. No manual step needed.
• Offline: Download the latest instructions.zip from releases and replace the contents of instructions/.

Uninstalling

Plugins:

• Claude Code: claude plugin uninstall rosetta@rosetta
• Cursor (marketplace): Remove the Rosetta plugin from your Cursor team/company marketplace install.
• Cursor (standalone): Delete the extracted .cursor/ plugin files from the repository.
• VS Code / GitHub Copilot (marketplace): Remove the Copilot agent plugin.
• VS Code / JetBrains / GitHub Copilot (standalone): Delete the extracted .github/ plugin files from the repository.
• Codex: Delete the extracted plugin files from the repository

HTTP/STDIO MCP:

• Claude Code: claude mcp remove Rosetta
• Codex: codex mcp remove Rosetta
• Cursor, VS Code, Windsurf, JetBrains, Antigravity, OpenCode: Remove the Rosetta entry from your MCP configuration file

Offline:

• Delete the instructions/ directory and the IDE instruction file content you added

Related Docs

• Plugins - plugin contents and capabilities
• Quick Start - fastest path to a working setup
• MCPs Installation - when and how to use the optional MCP path
• Overview - mental model and terminology
• Troubleshooting - common issues and fixes
• Deployment - org-wide server deployment