Frequently Asked Questions
General Questions
What is the CodeScene MCP Server?
The CodeScene MCP Server is a local MCP service that lets AI tools access CodeScene’s Code Health analysis directly from your codebase. This gives AI assistants the context they need to avoid introducing technical debt, safeguard AI‑generated code, and propose meaningful improvements.
What can I use it for?
Typical use cases include safeguarding AI‑generated code using Code Health metrics, guiding AI toward meaningful refactorings, simplifying code reviews, and motivating improvements through built‑in ROI calculations on refactoring work.
Which AI tools does it work with?
The server is designed to work with MCP‑enabled AI tools such as GitHub Copilot in VS Code, Cursor, Claude Code, and others that can connect to local or remote MCP servers.
Requirements and Setup
What are the prerequisites?
You need:
An active CodeScene subscription (Cloud or on-prem)
A
CS_ACCESS_TOKENso the MCP server can access CodeScene’s analysisOne of the following to run the MCP server:
Homebrew (macOS/Linux) — recommended for Mac and Linux users
PowerShell (Windows) — one-command installation
Docker — for a containerized, self-contained setup
Nothing else is required.
Where are the installation instructions?
You will find everything you need to get up and running with the MCP Server here: https://codescene.io/docs/developer-tools/mcp/codescene-mcp-server.html
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
Where does the CodeScene MCP Server run?
The MCP server is designed to run in your local environment, either as a native binary on your machine or inside a local Docker container.
Does the MCP server send my code to external services?
All analysis is performed locally in your environment, and communication with your CodeScene instance uses a secure token. No code or analysis data is sent to external cloud services unless you explicitly configure such integrations.
Use Cases and Benefits
How does the MCP server protect my codebase?
By exposing Code Health metrics and related insights to AI tools, the MCP server makes sure suggestions and refactorings account for structural and cognitive complexity, which helps prevent accidental introduction of technical debt.
How does the MCP Server help build a business case for refactoring?
The MCP server includes a tool called code_health_refactoring_business_case that uses CodeScene’s statistical model and industry benchmarks to estimate how Code Health improvements impact development velocity, defect rates, and maintenance costs. This makes it easier to justify refactoring work to business stakeholders. Simply ask as your AI tooling to make the business case for refactoring:
Which refactoring targets should we start with?
You should focus on modules or files that are frequently changed and have low Code Health, since they are high‑impact hotspots. The MCP server provides tools like list_technical_debt_hotspots and list_technical_debt_goals to surface these areas and align them with your technical debt strategy.
How do I refactor safely with the MCP Server?
If you are ready to make a fast, immediate impact, ask your AI tooling to improve the codehealth or go big and ask it to get your chosen file to a perfect code health score of 10
How does the MCP Server help AI understand existing code?
The MCP server gives AI assistants access to Code Health reviews, hotspots, technical debt goals, and organizational knowledge such as key authors for different parts of the codebase, so AI‑driven summaries and diagnostics are grounded in real project context.
How does ACE work together with AI tools?
CodeScene ACE, when enabled, restructures overly complex functions into smaller and more cohesive units before AI refactoring, making the code easier for AI agents to understand and modify safely. This creates a workflow where ACE improves modularity, AI performs precise refactorings, and Code Health guides both toward maintainable results.