MCP Integration
The Model Context Protocol (MCP) lets AI coding tools access your Octokraft data — health scores, analysis issues, architecture reviews, PR analyses — so they have full context about your codebase quality when helping you write code.
| Tool | Support |
|---|
| Claude Code | Full |
| Cursor | Full |
| Windsurf | Full |
| Claude Desktop | Full |
Setup
1. Create an API Key
Go to Settings > API Keys in your Octokraft 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 for details on key management.
The Octokraft MCP server communicates over stdio and requires two environment variables:
OCTOKRAFT_API_KEY — Your API key from step 1OCTOKRAFT_BASE_URL — Your Octokraft instance URL (defaults to https://api.octokraft.com)
Claude Code
Cursor
Windsurf
Claude Desktop
Add to your MCP configuration (.mcp.json in your project root or ~/.claude/mcp.json globally):{
"mcpServers": {
"octokraft": {
"command": "octokraft-mcp",
"env": {
"OCTOKRAFT_API_KEY": "your-api-key",
"OCTOKRAFT_BASE_URL": "https://api.octokraft.com"
}
}
}
}
Add to .cursor/mcp.json in your project root:{
"mcpServers": {
"octokraft": {
"command": "octokraft-mcp",
"env": {
"OCTOKRAFT_API_KEY": "your-api-key",
"OCTOKRAFT_BASE_URL": "https://api.octokraft.com"
}
}
}
}
Add to your Windsurf MCP configuration:{
"mcpServers": {
"octokraft": {
"command": "octokraft-mcp",
"env": {
"OCTOKRAFT_API_KEY": "your-api-key",
"OCTOKRAFT_BASE_URL": "https://api.octokraft.com"
}
}
}
}
Add to your Claude Desktop configuration file (claude_desktop_config.json):{
"mcpServers": {
"octokraft": {
"command": "octokraft-mcp",
"env": {
"OCTOKRAFT_API_KEY": "your-api-key",
"OCTOKRAFT_BASE_URL": "https://api.octokraft.com"
}
}
}
}
The octokraft-mcp binary is available from your Octokraft dashboard under Settings > Downloads, or as part of the self-hosted deployment package.
The Octokraft 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 Octokraft.
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 Octokraft 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.
