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] You must receive a prior approval from your manager and company to use it.

[!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

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

{
  "mcpServers": {
    "Rosetta": {
      "url": "[rosetta MCP production server URL]"
    }
  }
}

claude mcp add --transport http Rosetta [rosetta MCP production server URL]

codex mcp add Rosetta --url [rosetta MCP production server URL]
codex mcp login Rosetta

{
  "servers": {
    "Rosetta": {
      "url": "[rosetta MCP production server URL]"
    }
  }
}

{
  "servers": {
    "Rosetta": {
      "url": "[rosetta MCP production server URL]"
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "url": "[rosetta MCP production server URL]"
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "url": "[rosetta MCP production server URL]"
    }
  }
}

{
  "mcpServers": {
    "Rosetta": {
      "serverUrl": "[rosetta MCP production server URL]"
    }
  }
}

{
  "mcp": {
    "Rosetta": {
      "type": "http",
      "url": "[rosetta MCP production server URL]",
      "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": "[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 ims-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 ims-mcp@latest

{
  "servers": {
    "Rosetta": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ims-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": ["ims-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": ["ims-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": ["ims-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": ["ims-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", "ims-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 Architecture — Tradeoffs for rationale.

Plugin-Based Installation (pre-release)

Rosetta publishes plugins for supported IDEs. Each plugin installs core (20 skills, 7 agents, 4 workflows, bootstrap rules).

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

Claude Code

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

Updating after installation:

claude plugin marketplace update rosetta
claude plugin update core@rosetta

VS Code / GitHub Copilot

Install core-copilot via VS Code Copilot Plugins (not VS Code extensions).

JetBrains / GitHub Copilot

1. Download core-copilot-*.zip from the latest release
2. Create a .github folder in your repository and extract the archive contents into it
3. Delete files not needed for JetBrains: .github/.mcp.json, .github/hooks.json, .github/templates, .github/rules/bootstrap.md
4. Copy the contents of .github/rules/plugin-files-mode.md into .github/copilot-instructions.md and append before the closing </plugin_files_mode> tag: Rosetta plugin root: ".github", get_context_instructions: must read fully all five "cat .github/rules/bootstrap-*.md" files all lines. You MUST FOLLOW ALL instructions and then MUST select workflow and execute it. All workflows are stored in ".github/rules/<workflowtag>.md".
5. Enable in JetBrains GitHub Copilot settings: Agent Mode, Custom Agent, Coding Agent, Subagent, Skills

Codex

Download core-codex-*.zip from the latest release, extract on top of the repository, and enable hooks:

codex features enable codex_hooks

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 core@rosetta
• VS Code / GitHub Copilot: Remove the Copilot agent plugin
• Codex: Delete the extracted plugin files from the repository

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