Installation

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

When should I read this? When you need the full picture: HTTP, STDIO, plugins, offline, or environment variables. For the fastest path, see Quick Start.

[!WARNING] Use Sonnet 4.6, GPT-5.3-codex-medium, gemini-3.1-pro or better models. Avoid Auto model selection.

Choose Your Mode

Step 1: Install

Pick one mode and follow its section.

HTTP Transport (Recommended)

One URL, no local dependencies, OAuth handles authentication automatically.

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

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

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

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

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

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

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

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

{
  "mcp": {
    "Rosetta": {
      "type": "http",
      "url": "https://rosetta.evergreen.gcp.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

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": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

claude mcp add --transport stdio Rosetta \
  --env ROSETTA_SERVER_URL=https://ims.evergreen.gcp.griddynamics.net/ \
  --env ROSETTA_API_KEY=your-api-key \
  --env ROSETTA_USER_EMAIL=you@example.com \
  -- uvx ims-mcp@latest

codex mcp add Rosetta \
  --env ROSETTA_SERVER_URL=https://ims.evergreen.gcp.griddynamics.net/ \
  --env ROSETTA_API_KEY=your-api-key \
  --env ROSETTA_USER_EMAIL=you@example.com \
  -- uvx ims-mcp@latest

{
  "servers": {
    "Rosetta": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "servers": {
    "Rosetta": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "command": "uvx",
      "args": ["ims-mcp@latest"],
      "env": {
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net/",
        "ROSETTA_API_KEY": "your-api-key",
        "ROSETTA_USER_EMAIL": "you@example.com"
      }
    }
  }
}

{
  "mcp": {
    "Rosetta": {
      "type": "local",
      "command": ["uvx", "ims-mcp@latest"],
      "enabled": true,
      "env": {
        "ROSETTA_SERVER_URL": "https://ims.evergreen.gcp.griddynamics.net/",
        "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 Architecture — Tradeoffs for rationale.

Plugin-Based Installation

Rosetta publishes plugins for Claude Code and Cursor through the plugin marketplace. Install to your user profile for use across all projects.

Two modes:

• Lightweight (recommended): bootstrap rule and MCP server definition only. Smallest footprint, behavior driven by MCP.
• Full: core (20 skills, 7 agents, 4 workflows, bootstrap rules) plus optional grid enterprise extensions. Requires core 2.0.0+ for grid.

Read more about plugin contents and capabilities in the Usage Guide — Plugins.

Claude Code

claude plugin marketplace add griddynamics/rosetta

# Lightweight (recommended)
claude plugin install rosetta@rosetta

# Full
claude plugin install core@rosetta
claude plugin install grid@rosetta           # Enterprise (optional, requires core)

Cursor

Cursor uses .cursor-plugin/plugin.json and .cursor-plugin/marketplace.json manifests. See the plugin repository for Cursor-specific setup.

Offline Installation (No MCP)

For environments without network access to Rosetta Server.

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 bootstrap.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, bootstrap.md is always required.

Step 3: Verify

Applies to all installation modes. Ask the agent:

What can you do, Rosetta?

It should use Rosetta MCP to retrieve agents, guardrails, and instructions.

Step 4: Initialize Repository

Run once per repository after installation:

Initialize this repository using Rosetta

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

• HTTP: No action needed. Server-side upgrades apply automatically.
• STDIO: uvx ims-mcp@latest always pulls the newest published version. No manual step needed.
• Plugins: Plugins auto-upgrade or can be updated via claude plugin update.
• Offline: Download the latest instructions.zip from releases and replace the contents of instructions/.

Uninstalling

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

Plugins:

• Claude Code: claude plugin uninstall rosetta@rosetta (or core@rosetta, grid@rosetta for full install)
• Cursor: Remove the .cursor-plugin/ directory from your project

Offline:

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

Related Docs

• Quick Start - fastest path to a working setup
• Overview - mental model and terminology
• Troubleshooting - common issues and fixes
• Deployment - org-wide server deployment