CodeScene MCP Server

The CodeScene MCP Server exposes CodeScene’s Code Health analysis as local AI-friendly tools.

This server is designed to run in your local environment and lets AI assistants (like GitHub Copilot, Cursor, Claude code, etc.) request meaningful Code Health insights directly from your codebase.
The Code Health insights augment the AI prompts with rich content around code quality issues, maintainability problems, and technical debt in general.

> [!NOTE]
> The server is under development. Expect to get a proper packaged installation + more tools soon. Real soon.

Quick set-up

<details>

<summary>Claude Code</summary>

To connect with CodeScene Cloud:

export CS_ACCESS_TOKEN="<your token here>"
export PATH_TO_CODE="<your project dir here>"
claude mcp add codescene --env CS_ACCESS_TOKEN=$CS_ACCESS_TOKEN -- docker run -i --rm -e CS_ACCESS_TOKEN -e CS_MOUNT_PATH=$PATH_TO_CODE --mount type=bind,src=$PATH_TO_CODE,dst=/mount/,ro codescene/codescene-mcp

To connect with CodeScene On-prem:

export CS_ACCESS_TOKEN="<your token here>"
export CS_ONPREM_URL="<your onprem url>"
export PATH_TO_CODE="<your project dir here>"
claude mcp add codescene --env CS_ACCESS_TOKEN=$CS_ACCESS_TOKEN --env CS_ONPREM_URL=$CS_ONPREM_URL -- docker run -i --rm -e CS_ACCESS_TOKEN -e CS_ONPREM_URL -e CS_MOUNT_PATH=$PATH_TO_CODE --mount type=bind,src=$PATH_TO_CODE,dst=/mount/,ro codescene/codescene-mcp

Make sure to replace the PATH_TO_CODE with the absolute path to the directory whose read-only access you want the CodeScene MCP server to have.

ℹ️ You can read more about what is CS_MOUNT_PATH and why we need it in the Frequently Asked Questions section.

</details>

<details>

<summary>Codex CLI</summary>

Configure ~/.codex/config.toml depending on whether or not you use Cloud or On-prem.

CodeScene Cloud:

[mcp_servers.codescene]
command = "docker"
args = ["run", "--rm", "-i", "-e", "CS_ACCESS_TOKEN", "-e", "CS_MOUNT_PATH=<PATH_TO_CODE>", "--mount", "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro", "codescene/codescene-mcp"]
env = { "CS_ACCESS_TOKEN" = "<YOUR_ACCESS_TOKEN>" }

CodeScene On-prem:

[mcp_servers.codescene]
command = "docker"
args = ["run", "--rm", "-i", "-e", "CS_ACCESS_TOKEN", "-e", "CS_ONPREM_URL", "-e", "CS_MOUNT_PATH=<PATH_TO_CODE>", "--mount", "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro", "codescene/codescene-mcp"]
env = { "CS_ACCESS_TOKEN" = "<YOUR_ACCESS_TOKEN>", "CS_ONPREM_URL" = "<URL>" }

Make sure to replace the <PATH_TO_CODE> with the absolute path to the directory whose read-only access you want the CodeScene MCP server to have.

ℹ️ You can read more about what is CS_MOUNT_PATH and why we need it in the Frequently Asked Questions section.

</details>

<details>

<summary>GitHub Copilot CLI</summary>

After starting Copilot CLI, run the following command to add the CodeScene MCP server:

/mcp add

You will then need to provide information about the MCP server.

CodeScene Cloud:

- Server Name: codescene
- Server Type: Local (Press 1)
- Command: docker
- Arguments: run, --rm, -i, -e, CS_ACCESS_TOKEN, -e, CS_MOUNT_PATH=<PATH_TO_CODE>, --mount, "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro", codescene/codescene-mcp

CodeScene On-prem:

- Server Name: codescene
- Server Type: Local (Press 1)
- Command: docker
- Arguments: run, --rm, -i, -e, CS_ACCESS_TOKEN, -e, CS_ONPREM_URL, -e, CS_MOUNT_PATH=<PATH_TO_CODE>, --mount, "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro", codescene/codescene-mcp

Make sure to replace the <PATH_TO_CODE> with the absolute path to the directory whose read-only access you want the CodeScene MCP server to have.

ℹ️ You can read more about what is CS_MOUNT_PATH and why we need it in the Frequently Asked Questions section.

</details>

<details>

<summary>GitHub Copilot coding agent</summary>

GitHub Copilot coding agent can leverage the CodeScene MCP server directly in your CI/CD.

To add the secrets to your Copilot environment, follow the Copilot documentation. Only secrets with names prefixed with COPILOT_MCP_ will be available to your MCP configuration.

In your GitHub repository, navigate under Settings -> Code & automation -> Copilot -> Coding agent, and add the following configuration in the MCP configuration section.

CodeScene Cloud:

{
  "mcpServers": {
    "codescene": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CS_ACCESS_TOKEN=$CS_ACCESS_TOKEN",
        "-e",
        "CS_MOUNT_PATH=$CS_MOUNT_PATH",
        "--mount",
				"type=bind,src=$CS_MOUNT_PATH,dst=/mount/,ro",
        "codescene/codescene-mcp"
      ],
      "env": {
        "CS_ACCESS_TOKEN": "COPILOT_MCP_CS_ACCESS_TOKEN",
        "CS_MOUNT_PATH": "COPILOT_MCP_CS_MOUNT_PATH"
      },
      "tools": [""]
    }
  }
}

CodeScene On-prem:

{
  "mcpServers": {
    "codescene": {
      "type": "local",
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "CS_ACCESS_TOKEN=$CS_ACCESS_TOKEN",
        "-e",
        "CS_ONPREM_URL=$CS_ONPREM_URL",
        "-e",
        "CS_MOUNT_PATH=$CS_MOUNT_PATH",
        "--mount",
				"type=bind,src=$CS_MOUNT_PATH,dst=/mount/,ro",
        "codescene/codescene-mcp"
      ],
      "env": {
        "CS_ACCESS_TOKEN": "COPILOT_MCP_CS_ACCESS_TOKEN",
        "CS_ONPREM_URL": "COPILOT_MCP_CS_ONPREM_URL",
        "CS_MOUNT_PATH": "COPILOT_MCP_CS_MOUNT_PATH"
      },
      "tools": [""]
    }
  }
}

ℹ️ You can read more about what is CS_MOUNT_PATH and why we need it in the Frequently Asked Questions section.

</details>

<details>

<summary>Kiro</summary>

Create a .kiro/settings/mcp.json file in your workspace directory (or edit if it already exists), add the following configuration.

CodeScene Cloud:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", 
        "CS_ACCESS_TOKEN",
        "-e",
        "CS_MOUNT_PATH=<PATH_TO_CODE>",
        "--mount",
        "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro",
        "codescene/codescene-mcp"
      ],
      "env": {
        "CS_ACCESS_TOKEN": "<YOUR_TOKEN>",
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

CodeScene On-prem:

{
  "mcpServers": {
    "sonarqube": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", 
        "CS_ACCESS_TOKEN",
        "-e",
        "CS_ONPREM_URL",
        "-e",
        "CS_MOUNT_PATH=<PATH_TO_CODE>",
        "--mount",
        "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro",
        "codescene/codescene-mcp"
      ],
      "env": {
        "CS_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "CS_ONPREM_URL": "<URL>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Make sure to replace the <PATH_TO_CODE> with the absolute path to the directory whose read-only access you want the CodeScene MCP server to have.

ℹ️ You can read more about what is CS_MOUNT_PATH and why we need it in the Frequently Asked Questions section.

</details>

<details>

<summary>VS Code</summary>

Note: when installing the MCP server with the one-click install buttons, VS Code will install this configuration globally, available to every project you work on with VS Code. This means that when specifying the CS_MOUNT_PATH (what is CS_MOUNT_PATH?) you should either specify a more global path so that the MCP server can see files globally, or move the installed configuration to a per-project basis by making a .vscode/mcp.json file in your project and specifying the CS_MOUNT_PATH there to be just for said project.

</details>

<details>

<summary>Amazon Q CLI</summary>

To configure the Amazon Q CLI to have the CodeScene Cloud MCP server:

q mcp add --name codescene-mcp --command docker --args '["run", "--rm", "-i", "-e", "CS_ACCESS_TOKEN", "-e", "CS_MOUNT_PATH=<PATH_TO_CODE>", "--mount", "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro", "codescene/codescene-mcp"]'

To configure the Amazon Q CLI to have the CodeScene On-prem MCP server:

q mcp add --name codescene-mcp --command docker --args '["run", "--rm", "-i", "-e", "CS_ACCESS_TOKEN", "-e", "CS_ONPREM_URL", "-e", "CS_MOUNT_PATH=<PATH_TO_CODE>", "--mount", "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro", "codescene/codescene-mcp"]'

Make sure to replace the <PATH_TO_CODE> with the absolute path to the directory whose read-only access you want the CodeScene MCP server to have. In addition, make sure to have the CS_ACCESS_TOKEN (and CS_ONPREM_URL if you are using the on-prem variant) in your environment PATH, or specify them manually in the command.

ℹ️ You can read more about what is CS_MOUNT_PATH and why we need it in the Frequently Asked Questions section.

</details>

<details>

<summary>Amazon Q IDE</summary>

1. Access the MCP configuration UI
2. Choose the plus (+) symbol
3. Select the scope: do you want the MCP server to be available globally or locally?
4. In the Name field, enter CodeSceneMCPServer
5. Select stdio as the transport protocol
6. In the Command field, enter docker
7. In the Arguments field, enter:
CodeScene Cloud:
1. run
2. --rm
3. -i
4. -e
5. CS_ACCESS_TOKEN
6. -e
7. CS_MOUNT_PATH=<PATH_TO_CODE>
8. --mount
9. type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro
10. codescene/codescene-mcp
CodeScene On-prem:
1. run
2. --rm
3. -i
4. -e
5. CS_ACCESS_TOKEN
6. -e
7. CS_ONPREM_URL
8. -e
9. CS_MOUNT_PATH=<PATH_TO_CODE>
10. --mount
11. type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro
12. codescene/codescene-mcp
8. Fill in environment variables like CS_ACCESS_TOKEN (?) (and CS_ONPREM_URL if you are using On-prem). Make sure to replace <PATH_TO_CODE> with the absolute path to your code. You can read more about what is CS_MOUNT_PATH and why we need it in the Frequently Asked Questions section
9. Choose "Save"

Note: Amazon Q can only use the MCP server tools when used in the agentic mode.

</details>

---

Get a CS_ACCESS_TOKEN for the MCP Server

The MCP server configuration requires a CS_ACCESS_TOKEN which you get via your CodeScene instance. (The token grants access to the code health analysis capability).
For CodeScene Cloud you create the token here.
In CodeScene on-prem, you get the token via https://<your-cs-host><:port>/configuration/user/token.

Use Cases

> [!TIP]
> Watch the demo video of the CodeScene MCP.

With the CodeScene MCP Server in place, your AI tools can:

Safeguard AI-Generated Code

Prevent AI from introducing technical debt by flagging maintainability issues like complexity, deep nesting, low cohesion, etc.

Make Targeted Refactoring

AI tools can refactor code, but they lack direction on what to fix and how to measure if it helped. The Code Health tools solve this by giving AI assistants precise insight into design problems, as well as an objective way to assess the outcome: did the Code Health improve?

Understand Existing Code Before Acting

Use Code Health reviews to inform AI-driven summaries, diagnostics, or code transformations based on real-world cognitive and design challenges, not just syntax.

Frequently Asked Questions

<details>

<summary>I have multiple repos — how do I configure the MCP?</summary>

Since you have to provide a mount path for Docker, you can either have a MCP configuration per project (in VS Code that would be a .vscode/mcp.json file per project, for example) or you can mount a root directory within which all your projects are and then just use that one configuration instead.

</details>

<details>

<summary>Why are we mounting a directory in the Docker?</summary>

Previously we had the MCP client pass the entire file contents to us in a JSON object, but with this we ran into a problem where if the file contents exceed your AI model's input or output token limit, we'd either get no data or incorrect data.

While this might work for small files and code snippets, we want to provide a solution that works on any file, no matter the size, and we achieve this by having the MCP client return a file path to us which we then read ourselves, thus bypassing the AI token limit issue entirely.

To make this safe, we have you, the user, specify which path our MCP server should have access to. In addition, all the configuration examples provided in this README feature a mounting command that gives only read-only access to the mounted path, so we can't do anything to those files other than read them.

In addition this now saves your AI budget by not spending precious tokens on file reading, which can add up pretty quickly.

</details>

<details>

<summary>What is CS_MOUNT_PATH?</summary>

The CS_MOUNT_PATH should be an absolute path to the directory whose code you want to analyse with CodeScene. It can be either just a singular project, say at /home/john/Projects/MyProject, in which case the MCP server only sees and is able to reason about the files in that particular project, or it could be a more global path like /home/john/Projects, in which case the MCP server sees all of your projects.

The difference here really comes down to your preference. Do you want to give it more global access, but as such configure it just once, or do you want to give it more granular access, but then configure for each project / directory again each time.

</details>

<details>

<summary>Why do we specify CS_MOUNT_PATH twice?</summary>

Due to the limitation of not knowing the relative path to the file from within Docker, in order to read the correct file we need to know the full absolute path to your mounted directory, so that we could deduce a relative path to the internally mounted file by simply taking the absolute path to the file, the absolute path to the mounted directory, and replacing the mounted directory part with our internal mounted directory.

We pass the absolute path to the mounted directory to us via a environment variable -e CS_MOUNT_PATH=<PATH> so that we would know the absolute path, and then we need to pass that path again the second time via --mount type=bind,src=<PATH>,dst=/mount/,ro which then instructs Docker to actually mount <PATH> to our internal /mount/ directory.

</details>

Building the docker instance locally

You can build and run the dockerized CodeScene MCP server by first cloning the repo and then building the Docker image:

docker build -t codescene-mcp .

And then configuring the MCP in your editor, for example in VS Code:

"codescene-mcp": {
    "type": "stdio",
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CS_ACCESS_TOKEN",
        "-e",
        "CS_MOUNT_PATH=<PATH_TO_CODE>",
        "--mount",
        "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro",
        "codescene-mcp"
    ]
}

This configuration will automatically pick up the CS_ACCESS_TOKEN environment variable, but if you can't create a system-wide one then you can manually specify it like this:

"codescene-mcp": {
    "type": "stdio",
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "CS_ACCESS_TOKEN",
        "-e",
        "CS_MOUNT_PATH=<PATH_TO_CODE>",
        "--mount",
        "type=bind,src=<PATH_TO_CODE>,dst=/mount/,ro",
        "codescene-mcp"
    ],
    "env": {
		"CS_ACCESS_TOKEN": "token-goes-here",
    }
}

Or when running it from the CLI, like this:

docker run -i --rm -e CS_ACCESS_TOKEN=token-goes-here codescene-mcp

Note: if you want to use CodeScene On-prem, you need to additionally pass the CS_ONPREM_URL environment variable to it.