> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octokraft.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Integration

> Connect AI coding tools to Corbulo via Model Context Protocol

# MCP Integration

The Model Context Protocol (MCP) lets AI coding tools access your Corbulo data -- health scores, analysis issues, architecture reviews, PR analyses -- so they have full context about your codebase quality when helping you write code.

***

## Supported Tools

| Tool               | Support |
| ------------------ | ------- |
| **Claude Code**    | Full    |
| **Cursor**         | Full    |
| **Windsurf**       | Full    |
| **Claude Desktop** | Full    |

Any MCP-compatible tool can connect to the Corbulo MCP server.

***

## Setup

### 1. Create an API Key

Go to **Settings > API Keys** in your Corbulo project and create a new key. Give it a descriptive name like "MCP Server". Copy the key immediately -- it will not be shown again.

See [API Keys](/integrations/api-keys) for details on key management.

### 2. Configure Your Tool

The Corbulo MCP server communicates over stdio and requires two environment variables:

* `CORBULO_API_KEY` — Your API key from step 1
* `CORBULO_BASE_URL` — Your Corbulo instance URL (defaults to `https://api.corbulo.dev`)

<Tabs>
  <Tab title="Claude Code">
    Add to your MCP configuration (`.mcp.json` in your project root or `~/.claude/mcp.json` globally):

    ```json theme={null}
    {
      "mcpServers": {
        "corbulo": {
          "command": "corbulo-mcp",
          "env": {
            "CORBULO_API_KEY": "your-api-key",
            "CORBULO_BASE_URL": "https://api.corbulo.dev"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor">
    Add to `.cursor/mcp.json` in your project root:

    ```json theme={null}
    {
      "mcpServers": {
        "corbulo": {
          "command": "corbulo-mcp",
          "env": {
            "CORBULO_API_KEY": "your-api-key",
            "CORBULO_BASE_URL": "https://api.corbulo.dev"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windsurf">
    Add to your Windsurf MCP configuration:

    ```json theme={null}
    {
      "mcpServers": {
        "corbulo": {
          "command": "corbulo-mcp",
          "env": {
            "CORBULO_API_KEY": "your-api-key",
            "CORBULO_BASE_URL": "https://api.corbulo.dev"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    Add to your Claude Desktop configuration file (`claude_desktop_config.json`):

    ```json theme={null}
    {
      "mcpServers": {
        "corbulo": {
          "command": "corbulo-mcp",
          "env": {
            "CORBULO_API_KEY": "your-api-key",
            "CORBULO_BASE_URL": "https://api.corbulo.dev"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

<Note>
  The `corbulo-mcp` binary is available from your Corbulo dashboard under **Settings > Downloads**, or as part of the self-hosted deployment package.
</Note>

***

## Available Tools

The Corbulo MCP server exposes 17 tools organized by domain.

### Project

| Tool            | Description                                           |
| --------------- | ----------------------------------------------------- |
| `list_projects` | List all projects accessible with the current API key |
| `get_project`   | Get details for a specific project                    |

### Code Health

| Tool                      | Description                                                           |
| ------------------------- | --------------------------------------------------------------------- |
| `get_health_dashboard`    | Overall health score with category breakdown and active drift alerts  |
| `get_health_categories`   | All 8 health categories with weights, scores, and baseline thresholds |
| `get_health_assessment`   | Details for a specific assessment                                     |
| `list_health_assessments` | Assessment history over time                                          |
| `list_drift_alerts`       | Quality regressions detected between assessments                      |

### Analysis

| Tool                   | Description                                                         |
| ---------------------- | ------------------------------------------------------------------- |
| `list_analysis_issues` | All detected issues, with optional filters by severity and category |
| `get_issue_stats`      | Issue counts grouped by category and severity                       |
| `list_dismiss_rules`   | Active dismiss rules that suppress specific findings                |

### Architecture

| Tool                        | Description                                                      |
| --------------------------- | ---------------------------------------------------------------- |
| `get_architecture_overview` | Summary of the latest architecture review, conventions, and ADRs |
| `get_architecture_review`   | Latest architecture review with scores across 4 dimensions       |
| `list_conventions`          | Detected coding conventions with conformance rates               |
| `list_adrs`                 | Architecture decision records with lifecycle status              |

### Pull Requests

| Tool               | Description                                                              |
| ------------------ | ------------------------------------------------------------------------ |
| `get_pr_analysis`  | Analysis results for a specific PR, including merge readiness and issues |
| `list_pr_analyses` | PR analysis history                                                      |
| `get_pr_stats`     | Aggregate PR analysis statistics                                         |

***

## Example Usage

With the MCP server connected, your AI coding assistant can answer questions about your codebase using real data from Corbulo.

**You:** "What is the current state of our code health? Are there any critical issues I should focus on?"

Your AI assistant will call `get_health_dashboard` to retrieve the overall score and category breakdown, then `list_analysis_issues` filtered by critical severity to find the most important issues. The response includes specific file locations, issue descriptions, and which health categories are most affected.

**You:** "I am about to refactor the authentication module. What conventions does the codebase follow for error handling?"

Your AI assistant will call `list_conventions` to find error handling patterns detected in the codebase, and `get_architecture_review` for structural context about the module. This ensures the refactor follows established project patterns.

**You:** "Show me the drift alerts from the last week. What is causing our health score to drop?"

Your AI assistant will call `list_drift_alerts` to retrieve recent regressions, showing exactly which PRs introduced which issues and how they affected category scores.

***

## Security

MCP access through the Corbulo server is **read-only**. API keys used for MCP cannot:

* Modify project settings
* Trigger analyses or assessments
* Access raw source code
* Delete or dismiss issues
* Manage team members or permissions

The MCP server exposes only aggregated analysis results, scores, and metadata. Source code is never transmitted through the MCP interface.