Installing CodeScene Single-User MCP

CodeScene Single-User MCP gives your AI assistant local access to Code Health analysis so it can review code, safeguard AI-generated changes, support refactoring, and help communicate why Code Health matters.

Before you start

Make sure you have:

  • a single-user access token

  • an MCP-compatible AI assistant or editor

  • one supported installation method from the list below

Step 1: Choose an installation method

Pick the setup that fits your platform and workflow best.

Option 1: NPM / npx

This is the quickest way to get started.

Requirements:

  • Node.js 18 or later

Run the MCP server directly with npx:

npx @codescene/codehealth-mcp

Or install it globally:

npm install -g @codescene/codehealth-mcp

On first run, the correct platform-specific binary is downloaded automatically and cached for future use. Supported platforms for the NPM path are macOS ARM64, macOS AMD64, Linux ARM64, Linux AMD64, and Windows AMD64.

Option 2: Homebrew

Use this on macOS or Linux if you prefer installing with Homebrew.

brew tap codescene-oss/codescene-mcp-server https://github.com/codescene-oss/codescene-mcp-server

brew install cs-mcp

After installation, the cs-mcp command is available in your PATH. Some applications, including VS Code or Claude Desktop, may need a restart before PATH changes are picked up. Homebrew supports macOS ARM64, macOS AMD64, Linux ARM64, and Linux AMD64.

Option 3: Windows PowerShell

Use this on Windows for a simple one-command installation.

Requirements:

  • Windows 10 or later

  • PowerShell 5.1 or later

Run:

irm https://raw.githubusercontent.com/codescene-oss/codescene-mcp-server/main/install.ps1 | iex

This installs the latest version into %LOCALAPPDATA%\Programs\cs-mcp and adds it to your PATH. After installation, restart your terminal. Some applications, including VS Code or Claude Desktop, may also need a full restart before the new PATH is picked up.

Option 4: Docker

Use Docker if you want a self-contained setup.

Pull the latest image:

docker pull codescene/codescene-mcp

For Docker, both of the following are required:

  • CS_ACCESS_TOKEN

  • CS_MOUNT_PATH

CS_MOUNT_PATH must be an absolute path to the code directory that CodeScene MCP should analyze. The code is mounted read-only in the documented examples. Docker cannot read the host’s config file, so CS_ACCESS_TOKEN must be passed as an environment variable in the Docker setup.

Option 5: Manual download

You can also download the latest binary from the GitHub Releases page and add it to your PATH manually.

Supported platforms:

  • macOS ARM64 (Apple Silicon)

  • macOS AMD64 (Intel)

  • Linux ARM64

  • Linux AMD64

  • Windows AMD64

After downloading, make the binary executable and optionally move it into your PATH so your MCP client can call it as cs-mcp.

chmod +x cs-mcp
mv cs-mcp /usr/local/bin/cs-mcp

The exact filename differs by platform.

Step 2: Get your single-user access token

You can find the complete token signup and setup flow in our article How to start your Single-User MCP free trial and get your access token, including where to find the token email and how to use the token in your MCP configuration.

Step 3: Copy the AI guidance file into your repository

Copy the AGENTS.md file into your repository.

This file guides AI agents on how to use CodeScene MCP correctly, including safeguard workflows for AI-touched code and the recommended approach for Code Health-guided refactoring.

If you use Amazon Q, copy the .amazonq/rules directory instead.

Step 4: Add CodeScene Single-User MCP to your MCP client

Add CodeScene MCP to your MCP client and set your single-user token as CS_ACCESS_TOKEN. The MCP repo documents example configurations for native binaries, npx, Docker, and common editors such as VS Code, GitHub Copilot, Cursor, Claude Code, Kiro, and Amazon Q.

Example: static binary (cs-mcp)

{
  "servers": {
    "codescene": {
      "type": "stdio",
      "command": "cs-mcp",
      "env": {
        "CS_ACCESS_TOKEN": "<your single-user token here>"
      }
    }
  }
}

This is the same documented pattern used for the native binary setup.

Example: npx

{
  "servers": {
    "codescene": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@codescene/codehealth-mcp"
      ],
      "env": {
        "CS_ACCESS_TOKEN": "<your single-user token here>"
      }
    }
  }
}

This follows the documented npx setup flow.

Example: Docker

Replace /path/to/your/code with the absolute path to your repository:

{
  "servers": {
    "codescene": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CS_ACCESS_TOKEN",
        "-e",
        "CS_MOUNT_PATH=/path/to/your/code",
        "--mount",
        "type=bind,src=/path/to/your/code,dst=/mount/,ro",
        "codescene/codescene-mcp"
      ],
      "env": {
        "CS_ACCESS_TOKEN": "<your single-user token here>"
      }
    }
  }
}

This follows the documented Docker pattern, including the required CS_MOUNT_PATH and read-only bind mount.

Step 5: Run your first checks

Good first prompts:

  1. Review the Code Health of the current file.

  2. Score the current file and explain what lowers the score.

  3. Safeguard my staged changes before I commit them.

  4. Analyze this change set before I open a pull request.

✅ Success insight: CodeScene Single-User MCP is now ready to help your AI assistant review local code, safeguard code changes, support refactoring, and work with Code Health directly in your repository.