Skip to main content
CodeHealth™ MCP server (Suite Edition)

Quick Start Guide: Running CodeScene's MCP Server with OpenCode

The CodeScene CodeHealth™ MCP server works with OpenCode, the open-source AI coding agent. Once connected, your agent can check the Code Health of the code it writes, safeguard changes before you commit, and run a pre-flight check before you open a pull request. This guide covers setup and how to get the most out of it.

Who is this for? CodeScene customers (Cloud or On-Prem) who use OpenCode. The MCP server is included with your CodeScene licence. If you use a standalone single-user MCP licence instead, see Installing CodeScene Single-User MCP.

Quick setup (OpenCode 2.0 and later)

OpenCode can install and configure MCP servers for you so you don’t need to edit any config files.

Ask OpenCode:

“Install the CodeScene MCP server from https://github.com/codescene-oss/codescene-mcp-server”

If you use CodeScene On-Prem, include your instance URL in the same request, for example “…and set CS_ONPREM_URL to https://<your-codescene-host>”.

OpenCode picks up the new server right away. Then jump to Sign in to CodeScene.

Manual setup

Use these steps if you’re on an older version of OpenCode or if you want a config file to commit for your whole team.

Install the MCP server

Choose one of the following:

Note: The Docker image is being retired and receives bug fixes only until 31 December 2026. Use one of the options above for new setups.

Add CodeScene to OpenCode

Add the server under the mcp key in your OpenCode config. Use opencode.json in your project root to enable it for one repository, or ~/.config/opencode/opencode.json to enable it everywhere.

If you installed with Homebrew, PowerShell or a manual download:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codescene": {
      "type": "local",
      "command": ["cs-mcp"],
      "enabled": true
    }
  }
}

If you use npx: replace the command line with "command": ["npx", "-y", "@codescene/codehealth-mcp"].

CodeScene On-Prem: add your instance URL as an environment variable:

      "environment": {
        "CS_ONPREM_URL": "https://<your-codescene-host>"
      }

Sign in to CodeScene

Recommended: OAuth. Ask OpenCode to "Log me in to CodeScene". The agent starts the sign-in flow and opens your browser. No token is needed. If you have more than one CodeScene Cloud account, you can also say "Set my CodeScene account ID to <id>"; the account ID is the number shown under My Account in CodeScene Cloud.

Alternative: Personal Access Token. Useful for shared or headless environments. Create a token:

  • CodeScene Cloud: codescene.io/users/me/pat

  • CodeScene On-Prem: Configuration > Authentication > Personal Access Tokens, or https://<your-codescene-host>/configuration/user/token

Then add it to the environment block of your config:

      "environment": {
        "CS_ACCESS_TOKEN": "<your token>"
      }

If CS_ACCESS_TOKEN is set, the server uses it instead of an OAuth session. Don't commit a project-level opencode.json that contains a token to source control; use the global config or an environment variable instead.

Check your setup: ask OpenCode to "Verify my CodeScene MCP installation". This runs PASS/FAIL checks on setup, authentication and connectivity.

Add the agent guidance file

Copy the guidance file from the MCP server repository into the root of your repository as AGENTS.md. OpenCode reads AGENTS.md automatically, and the file tells the agent when to check Code Health and how to act on the results.

If your repository already has an AGENTS.md, append the CodeScene section to it.

Use it well

We recommend three checks, each at a different point in the workflow:

  • While the agent writes or changes code: code_health_review gives a detailed review of a file, including the specific code smells to fix.

  • Before each commit: pre_commit_code_health_safeguard checks modified and staged files for Code Health regressions.

  • Before opening a pull request: analyze_change_set reviews every file changed against your base branch, as a local pre-flight check.

Start with healthy code. AI agents perform best in healthy code (around Code Health 9.5 and above).

Example prompts

  • "Run a Code Health review on this file and explain the most important issues."

  • "Refactor this function to fix the code smells, then re-check the Code Health score."

  • "Safeguard my staged changes before I commit."

  • "Analyze my change set against main before I open a PR."

  • "Make a business case for refactoring this file."

Hotspot, technical debt goal and code ownership tools require a CodeScene Cloud or On-Prem subscription. Code Health review, safeguard and change-set tools work with any valid licence.

Tip: If your OpenCode setup offers a model selector, use a frontier model for the best refactoring results. Always review AI-generated changes before committing them.

Further reading

Was this helpful?

Still need help? Ask the team