CodeScene MCP Server: Bring Code Health Insights Into Your AI Workflow¶

The CodeScene MCP Server makes AI tools more helpful and reliable by grounding them in Code Health data.

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.

Safeguard AI-generated code using the Code Health metrics.
Guide AI toward meaningful improvements and refactorings.
Simplify code reviews by ensuring the AI only generates healthy code.
Motivate Code Health improvements in business terms via the built-in ROI calculation.

💡 Tip: Watch the 2-min demo video of CodeScene MCP

⚠ Attention: This document describes early access features. The MCP Server is in Beta stage, and available for opt-in customers. Contact your CodeScene Account Executive for more info 👍

Quick Start Guide¶

The CodeScene MCP server is packaged as a self-contained docker image. The MCP server is distributed via the Official MCP Registry .

Follow these steps to launch the server:

Install Docker .
Get a CS_ACCESS_TOKEN for the MCP Server The token allows the server to access CodeScene’s code health analysis.
- For CodeScene Cloud, create the token here: https://codescene.io/users/me/pat
- For CodeScene on-prem, the token is available at: https://<your-cs-host>:<port>/configuration/user/token
Copy the AGENTS.md file to your repository. This file guides AI agents on how to use the MCP, including rules that safeguard AI coding.
Follow the steps in the quick setup for your specific AI IDE/environment.

CodeScene MCP Use Cases¶

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

Safeguard AI-Generated Code¶

The CodeScene MCP server prevents AI tools from introducing technical debt by surfacing maintainability issues such as high complexity, deep nesting, low cohesion, and unstable hotspots.

This is aligned with CodeScene’s goal of Strengthening the Inner Developer Loop , turning AI from a code generator into an engineering partner that understands and protects Code Health.

Fig. 20 Example where the CodeScene MCP enables an AI to fact-check itself, ensuring the generated code remains maintainable and AI-friendly.¶

⚠️ Unhealthy Code Undermines AI-Assisted Development: Organizations that want safe, reliable, and effective AI-assisted development must invest in Code Health as a foundational capability.

Uplift Unhealthy Code: Refactoring With ACE + AI¶

AI works best on healthy, modular code. Many legacy functions are too large or complex for reliable AI refactoring, which leads to poor suggestions and unstable changes. CodeScene ACE , exposed through the MCP server, helps by first restructuring these complex functions into smaller and more cohesive units. This modularity makes the code far easier for AI agents to understand and refactor safely.

The result is a cooperative workflow where:

CodeScene ACE improves modularity and structure,
AI performs more precise refactorings, and
Code Health guides both toward maintainable outcomes.

Fig. 21 AI performs a directed refactoring by invoking CodeScene ACE, and verifies the outcome objectively via the MCP Server.¶

🎗️ ACE is a CodeScene add-on and requires an additional license. You can request access and more info here .

Understand Existing Code Before Acting¶

AI assistants benefit from understanding the context behind the code. CodeScene MCP provides access to Code Health reviews, hotspots, technical debt goals, and organizational knowledge such as the key authors behind different parts of the codebase. That way, AI-driven summaries and diagnostics become grounded in real-world facts.

FAQ¶

Below are common questions when getting started with the CodeScene MCP Server.

General questions¶

What is the CodeScene MCP Server?¶

It is a local MCP service that lets AI tools access CodeScene’s Code Health analysis. This gives AI assistants the context they need to avoid introducing technical debt, safeguard AI generated code, and propose meaningful improvements.

What are the prerequisites?¶

You need:

An active CodeScene subscription (Cloud or on-prem)
Docker installed on your machine
A CS_ACCESS_TOKEN so the MCP server can access CodeScene’s analysis

Nothing else is required.

Where do I get the access token?¶

For CodeScene Cloud: https://codescene.io/users/me/pat

For on-prem CodeScene: https://<your-cs-host>:<port>/configuration/user/token

Does the MCP Server require a CodeScene ACE License?¶

No, the MCP Server works well without ACE and you can still benefit from AI safeguarding, Code Health feedback, etc. CodeScene ACE is an optional add-on that gives you directed and checked refactorings. It’s a great inital step when uplifting existing code. ACE helps by first restructuring complex functions into smaller and more cohesive units. This modularity makes the code far easier for AI agents to understand and refactor safely.

Get more info on ACE and request access here .

Privacy and Security¶

Scope and Config Questions¶

Why do I need to copy AGENTS.md to my repository?¶

AI tools read this file to understand how to use the MCP. The file contains rules that safeguard AI coding, prevent regressions, and ensure agents respect Code Health metrics.

Does the MCP server support multiple programming languages?¶

Yes. CodeScene supports 30+ programming languages, so the MCP server works across your polyglot codebase.

Does CodeScene MCP work with GitHub Copilot?¶

Yes. Copilot is one of the recommended environments for the MCP server. Follow the quick setup instructions in the repository for your specific IDE.

What if I use Amazon Q?¶

Instead of AGENTS.md, copy the .amazonq/rules directory from the CodeScene MCP repository . These rules tailor the guidance to Amazon Q’s agent framework.

Purpose: Key MCP Use Cases¶

How does the MCP server protect my codebase?¶

By exposing Code Health metrics to AI tools, the MCP server ensures that suggestions, refactorings, and generated code take real structural and cognitive complexity into account. This prevents accidental introduction of technical debt, and gives your team an objective code quality standard.

How does CodeScene help me make a business case for refactoring?¶

CodeScene doesn’t just highlight code smells or technical debt — it links code quality to business outcomes.

👉 This ROI calculation is built-in to the MCP via the tool code_health_refactoring_business_case.

Using our validated statistical model and industry benchmarks, you can estimate how improving Code Health translates into:

Increased development velocity
Fewer defects
Lower maintenance cost

That makes it easier to justify refactoring investments to stakeholders.

Fig. 22 Make a business case for larger refactoring efforts. Note that the case is based on the next tangible Code Health level, not necessarily a perfect 10.0.¶

See the benchmarking study for more details: How Refactoring Speeds Development by 43%

Which refactoring targets should we start with?¶

Focus on modules or files that are both frequently changed and have low Code Health — these are high-impact hotspots. The MCP server offers two tools for this purpose:

Use list_technical_debt_hotspots to surface the most important and risky areas.
Use list_technical_debt_goals to align your recommendations with the project’s strategic objectives.

Where can I find full setup instructions and more details?¶

All detailed instructions are in the GitHub repository: https://github.com/codescene-oss/codescene-mcp-server

AGENTS.md <https://github.com/codescene-oss/codescene-mcp-server/blob/main/AGENTS.md> is readable, and offers a good overview of the supported MCP tools as well as the key use cases. Check it out.

CodeScene MCP Server: Bring Code Health Insights Into Your AI Workflow¶

Quick Start Guide¶