How do I use Codacy MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Codacy MCP Server run a security audit on my repository" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Codacy MCP Server

by renatomarinho

Overview Schema Source Related Servers Discussions Admin

TypeScript

Codacy MCP Server — Vurb.ts Edition

The official Codacy MCP Server reimagined with the Vurb.ts framework — structured perception for AI agents.

Vurb.ts License TypeScript

11 Tools - 44 actions available on-demand

Related MCP server: CodeAlive MCP

3 Prompts MCP prompts — code-review, security-audit, repo-health

IMPORTANT

🤖 Zero lines of human code.

An AI agent (Antigravity, Opus 4.6) read a framework's llms.txt and a 488-line skill file. That's all it knew about Vurb.ts. From that, it built a complete production codebase from scratch: 11 tools · 44 actions · 12 models · 11 presenters · 3 prompts · 105 tests No human wrote a single line.

The thesis of Vurb.ts: if an AI agent can learn a framework from its llms.txt and produce production-grade code on the first attempt — the framework is doing its job.

NOTE

📐 Designed for agents, not for humans.

Traditional frameworks optimize for human ergonomics — tutorials, documentation, months of learning curve. Vurb.ts inverts this entirely. Its fluent API, llms.txt, and skill system were designed so that an AI agent can become productive in a single context window. The learning curve isn't short — it's zero. The agent reads the spec, understands the patterns, and ships. This codebase is the proof.

Why Vurb.ts?

The original Codacy MCP Server is a solid, production-grade implementation. This edition rebuilds it using the Vurb.ts MVA (Model · View · Agent) pattern — a framework designed specifically for MCP servers that gives AI agents structured, high-fidelity perception instead of raw JSON dumps.

Key advantages of the Vurb.ts approach:

🧠 Structured Perception — Presenters transform raw API data into optimized, LLM-readable formats with semantic annotations, HATEOAS navigation links, and severity-based suggestions
🛡️ Guardrails — Middleware (requireAuth), egress limits, idempotent mutation markers, and DLP redaction (secrets are stripped before reaching the wire)
📋 Prompt Templates — First-class support for MCP prompts (code-review, security-audit, repo-health) with dynamic argument injection
🔄 State Sync — Declarative cache invalidation policies ensure mutations automatically refresh dependent queries
🧩 Fluent API — Each tool action is defined as a composable, type-safe chain — no manual JSON schemas or handler wiring
📦 Zero Code Generation — No auto-generated OpenAPI client; a lightweight typed HTTP client is all that's needed
🗂️ Grouped Exposition — 44 actions exposed as 11 namespace tools, avoiding context window explosion

Capability Matrix

Capability	Original	Vurb.ts
Security & DLP
Auth middleware with self-healing errors	❌	✅
Secret redaction before wire (DLP)	❌	✅
Egress size limits per action	❌	✅
Safe process execution (`execFileSync`) for analysis	❌	✅
Determinism & Guardrails
Typed input schemas (Zod)	❌	✅
Idempotent mutation markers	❌	✅
Declarative cache invalidation	❌	✅
`.instructions()` with common-mistake guardrails	❌	✅
Tool-redirection hints (cross-agent navigation)	❌	✅
LLM Optimization
Grouped tool exposition (−78% context tokens)	❌	✅
HATEOAS navigation links in responses	❌	✅
Severity-aware action suggestions	❌	✅
Presenter-formatted tables (vs raw JSON)	❌	✅
MCP Protocol
`tools/list`	✅	✅
`tools/call`	✅	✅
`prompts/list` + `prompts/get`	❌	✅
State sync / cache control headers	❌	✅
Developer Experience
Auto-discovery (zero manual imports)	❌	✅
Fluent builder API	❌	✅
Test suite (105 tests)	❌	✅
Hot-reload dev server	❌	✅

Grouped Tool Exposition — Solving Context Explosion

This is the single most important architectural difference between the two implementations.

The Problem

The original server registers 24 flat tools in the MCP tools/list response. Every one of them — with its full name, description, and JSON Schema — is injected into the LLM's system prompt at the start of every conversation. This means the model must process ~4,000 tokens of tool definitions before the user even types a word.

At 44 actions, a flat approach would be even worse — ~7,000+ tokens consumed permanently just by tool schemas, leaving less room for actual conversation and reasoning.

The Solution: `toolExposition: 'grouped'`

Vurb.ts introduces grouped tool exposition. Instead of exposing 44 individual tools, the MCP server advertises only 11 namespace routers:

Original (flat)                    Vurb.ts (grouped)
─────────────────────              ──────────────────────
codacy_list_organizations          codacy_organizations     → 2 actions
codacy_list_organization_repos     codacy_repositories      → 3 actions
codacy_list_repository_issues      codacy_issues            → 7 actions
codacy_search_org_srm_items        codacy_security          → 6 actions
codacy_search_repo_srm_items       codacy_tools             → 6 actions
codacy_list_files                  codacy_files             → 4 actions
codacy_get_file_issues             codacy_pull_requests     → 6 actions
codacy_get_file_coverage           codacy_commits           → 3 actions
codacy_get_file_clones             codacy_overview          → 2 actions
codacy_get_file_with_analysis      codacy_quality           → 3 actions
codacy_list_repository_pull_reqs   codacy_cli               → 2 actions
codacy_get_repository_pull_req     ──────────────────────
codacy_list_pull_request_issues    11 tools in system prompt
                                   44 actions available on-demand
codacy_get_pr_files_coverage
codacy_get_pr_git_diff
codacy_get_repository_analysis
codacy_list_tools
codacy_list_repo_tools
codacy_get_pattern
codacy_list_repo_tool_patterns
codacy_get_issue
codacy_setup_repository
codacy_cli_analyze
codacy_cli_install
─────────────────────
24 tools in system prompt

How the LLM Navigates

The model interacts with the 11 namespace tools using an action parameter. It works like a progressive disclosure pattern:

Step 1 — Discovery. The LLM sees 11 high-level tools with concise descriptions. Each tool's schema has an action enum listing available actions:

codacy_security → actions: [search_org, search_repo, dashboard, sbom_search, ossf_scorecard, ignore]

Step 2 — Selection. When the user asks "show me security vulnerabilities in my repo", the LLM picks codacy_security with action: "search_repo". The remaining 43 action schemas are never loaded into context.

Step 3 — Navigation. Presenters include HATEOAS-style links in their response, guiding the LLM to the next logical tool:

🔗 Next steps: codacy_issues.list (for code quality) · codacy_security.dashboard (for summary)

Context Window Impact

Metric	Original (flat)	Vurb.ts (grouped)
Tools in `tools/list`	24	11
Actions available	24	44 (+83%)
JSON Schema surface (tool definitions)	29,316 chars across 718 lines	Derived from fluent chain — no hand-written schemas

Fewer tools in the system prompt means the LLM spends less context budget on tool schemas and more on actual reasoning — a critical advantage for models with limited context windows.

Developer Experience — Side by Side

The same security search tool in both implementations:

// tools/searchSecurityItemsTool.ts (124 lines)
export const searchRepositorySecurityItemsTool = {
  name: toolNames.CODACY_LIST_REPOSITORY_SRM_ITEMS,
  description: `Tool to list security...
   \n ${rules}
   \n ${generalRepositoryMistakes}`,
  inputSchema: {
    type: 'object',
    properties: {
      ...repositorySchema,
      ...getPaginationWithSorting('...'),
      options: {
        type: 'object',
        properties: {
          priorities: {
            type: 'array',
            items: { type: 'string',
              enum: ['Low','Medium','High','Critical']
            },
          },
          scanTypes: { /* ... 20 more lines */ },
          categories: { /* ... 15 more lines */ },
          statuses: { /* ... 8 more lines */ },
        },
      },
    },
    required: ['provider','organization','repository'],
  },
};

// handlers/security.ts (35 lines)
export const handler = async (args: any) => {
  const { provider, organization, repository,
    cursor, limit, sort, direction, options
  } = args;
  return await SecurityService.searchSecurityItems(
    provider, organization,
    cursor, limit, sort, direction,
    { ...options, repositories: [repository] }
  );
};

// index.ts — manual tool registration
codacy_search_repository_srm_items: {
  tool: Tools.searchRepositorySecurityItemsTool,
  handler: Handlers.searchRepoSecurityItemsHandler,
},

// codacy_security.tool.ts — complete
export const searchRepo = security
  .query('search_repo')
  .describe('Search security findings within a repository.')
  .instructions(`Repo-level security search.
    Uses the organization-level API filtered by repo.
    Scan types: SAST, SCA, Secrets, IaC, CICD.
    DAST and PenTesting are org-level only.`)
  .fromModel(CodacyScopeModel, 'repo')
  .withOptionalEnum('priority', SEVERITY_LEVELS)
  .withOptionalEnum('category', SECURITY_CATEGORIES)
  .withOptionalEnum('scanType', REPO_SCAN_TYPES)
  .withOptionalEnum('status', SECURITY_STATUSES)
  .withOptionalNumber('cursor')
  .withOptionalNumber('limit')
  .egress(1 * 1024 * 1024)
  .returns(SecurityPresenter)
  .handle(async (input, ctx) => {
    const body = { repositories: [input.repository] };
    if (input.priority) body.priorities = [input.priority];
    if (input.category) body.categories = [input.category];
    return ctx.client.post(
      `organizations/${input.provider}/${input.organization}/security/search`,
      body,
      { cursor: input.cursor, limit: input.limit ?? 50 },
    );
  });

What you don't write with Vurb.ts:

❌ No JSON Schema objects — input types derived from fluent chain
❌ No handler wiring — autoDiscover() replaces manual registration
❌ No OpenAPI codegen — lightweight HTTP client replaces 3,000+ generated lines
❌ No any types — full type inference from model to presenter

🔒 What Reaches the LLM — The Security Gap

The original server sends every API field directly to the LLM provider via JSON.stringify (index.ts:172). No filtering, no size limit, no redaction.

Here is what happens to each field from a Secrets detection scan:

API Field	❌ Without Vurb.ts	✅ With Vurb.ts	How
`title`	`"Hardcoded AWS Secret Key"` → sent to LLM	`"Hardcoded AWS Secret Key"` → sent to LLM	—
`priority`	`"Critical"` → sent to LLM	`🔴 Crit` → semantic badge	Presenter
`apiToken`	⚠️ `"cda_tk_9f8e7d6c5b4a3..."` → sent to LLM	`[REDACTED]`	`redactPII`
`internalId`	⚠️ `948271` → sent to LLM	Gone — never serialized	Schema stripping
`orgId`	⚠️ `"org_5f8a2b1d"` → sent to LLM	Gone — never serialized	Schema stripping
`suggestion.patchUrl`	⚠️ `"/api/v3/internal/patches/..."` → sent to LLM	Gone — never serialized	Schema stripping
`_links`	⚠️ Full internal API surface → sent to LLM	Gone — never serialized	Schema stripping
247 findings	All 247 dumped (1,000+ lines)	Top results only	`agentLimit: 100`
Response size	Unbounded	Max 1 MB	`.egress(1 * 1024 * 1024)`
Next action	LLM must guess	`→ codacy_security.ignore`	`suggestActions()`

Architecture Comparison

Metrics (verified)

Every number below was measured directly from the source code.

Metric	Original	Vurb.ts	Diff
Source files (hand-written)	45	42	−3
Tool definitions (`src/tools/`)	718 lines	—	—
Handlers (`src/handlers/`)	424 lines	—	—
Agents (`src/agents/` — tool + handler in one file)	—	763 lines	−33% vs tools+handlers
Tools in `tools/list` response	24	11	−54%
Actions available to the LLM	24	44	+83%
MCP Prompts	0	3	+3
Test cases	0	105	+105
Runtime dependencies	6	4	−33%
Dev dependencies	9	3	−67%

Tool Actions (44)

codacy_organizations (2)

Action	Description
`list`	List organizations the authenticated user belongs to
`list_repos`	List repositories in an organization

codacy_repositories (3)

Action	Description
`get`	Get repository details with analysis metrics
`list_branches`	List branches of a repository
`setup`	Add or follow a repository (multi-step orchestration)

codacy_issues (7)

Action	Description
`list`	Search and filter code quality issues
`get`	Get detailed issue information
`file_issues`	Get issues for a specific file
`pr_issues`	Get issues in a pull request
`quickfix_patch`	Download auto-fix patches
`ignore`	Mark an issue as ignored
`bulk_ignore`	Batch ignore multiple issues

codacy_security (6)

Action	Description
`search_org`	Search org-level security findings
`search_repo`	Search repo-specific security findings
`dashboard`	Get security dashboard summary
`sbom_search`	Search SBOM dependencies
`ossf_scorecard`	Get OSSF Scorecard for a package/repo
`ignore`	Ignore a security finding

codacy_tools (6)

Action	Description
`list`	List all analysis tools available
`repo_tools`	List tools configured for a repository
`get_pattern`	Get a specific code pattern definition
`repo_patterns`	List patterns for a tool in a repository
`configure`	Enable/disable a tool for a repository
`update_patterns`	Enable/disable specific patterns

codacy_files (4)

Action	Description
`list`	List files with analysis metrics
`get`	Get file details with metrics
`coverage`	Get line-by-line coverage
`clones`	Get code duplication blocks

codacy_pull_requests (6)

Action	Description
`list`	List PRs with analysis status
`get`	Get PR details with quality results
`coverage`	Get file-level PR coverage
`diff`	Get the Git diff
`trigger_ai_review`	Trigger AI-powered code review
`bypass`	Bypass the quality gate

codacy_commits (3)

Action	Description
`list`	List commits with analysis status
`get`	Get commit details with delta statistics
`issues`	Get issues introduced by a commit

codacy_overview (2)

Action	Description
`issues`	Aggregated issue overview with charts
`categories`	Issue count breakdown by category

codacy_quality (3)

Action	Description
`get_settings`	Get quality gate thresholds for a repository
`list_policies`	List gate policies for an organization
`get_policy`	Get details of a specific gate policy

codacy_cli (2)

Action	Description
`analyze`	Run local analysis via CLI
`install`	Install the CLI

Setup

Requirements

Node.js ≥ 18
A Codacy Account API Token

Configuration

Add to your MCP client configuration (Cursor, VS Code, Claude Desktop, etc.):

{
  "mcpServers": {
    "codacy": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Development

npm install
npm run build      # Compile TypeScript
npm run dev        # Vurb dev server (hot-reload)
npm test           # Run 105 tests
npm run inspect    # MCP Inspector

Project Structure

src/
├── agents/              # Tool definitions (Fluent API)
│   ├── codacy_organizations.tool.ts
│   ├── codacy_repositories.tool.ts
│   ├── codacy_issues.tool.ts
│   ├── codacy_security.tool.ts
│   ├── codacy_tools.tool.ts
│   ├── codacy_files.tool.ts
│   ├── codacy_pull_requests.tool.ts
│   ├── codacy_commits.tool.ts
│   ├── codacy_overview.tool.ts
│   ├── codacy_quality.tool.ts
│   └── codacy_cli.tool.ts
├── models/              # Zod schemas (data contracts)
├── views/               # Presenters (LLM-optimized output)
├── middleware/           # Auth, validation
├── prompts/             # MCP prompt templates
├── utils/               # Constants, rules, types
├── context.ts           # API client + context factory
├── index.ts             # Registry
└── server.ts            # Entry point

Usage (MCP stdio)

This server runs as a stdio MCP transport — the AI client launches it as a subprocess and communicates via stdin/stdout.

Cursor / Windsurf / Claude Desktop

Add to your MCP configuration file:

Cursor: .cursor/mcp.json
Windsurf: .codeium/windsurf/mcp_config.json
Claude Desktop: claude_desktop_config.json

{
  "mcpServers": {
    "codacy": {
      "command": "node",
      "args": ["/absolute/path/to/codacy-vurb/dist/server.js"],
      "env": {
        "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

VS Code (Copilot)

Add to your settings.json (Ctrl+Shift+P → Preferences: Open User Settings (JSON)):

{
  "mcp": {
    "servers": {
      "codacy": {
        "command": "node",
        "args": ["/absolute/path/to/codacy-vurb/dist/server.js"],
        "env": {
          "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>"
        }
      }
    }
  }
}

Get your token

Go to Codacy Account → Access Management
Generate an Account API Token
Paste it in the CODACY_ACCOUNT_TOKEN field above

Build & run

npm install
npm run build
# The server starts automatically when the MCP client launches it via stdio

License

Apache 2.0 — see LICENSE.

Available Tools

5 tools

codacy_overviewA

Read-only

[INSTRUCTIONS] Returns category-level counts — use these to identify which category has the most issues, then drill down with codacy_issues.list filtering by that category.

Get issue count breakdown by quality category (Security, Performance, CodeStyle, etc.).. Select operation via the action parameter. Actions: categories, issues

Workflow:

'categories': [INSTRUCTIONS] Returns category-level counts — use these to identify which category has the most issues, then drill down with codacy_issues.list filtering by that category.

Get issue count breakdown by quality category (Security, Performance, CodeStyle, etc.).

'issues': [INSTRUCTIONS] Returns server-rendered ECharts pie charts. Do NOT try to recalculate or re-render — present them as-is. Use the breakdown to identify highest-impact areas, then drill down with codacy_issues.list using appropriate filters.

Get aggregated issue overview with server-rendered pie charts by category and severity. [Cache-Control: no-store]

ParametersJSON Schema

Name	Required	Description
`action`	Yes	Which operation to perform
`provider`	No	Git provider. For: categories, issues
`branchName`	No	Branch name. For: issues
`repository`	No	Repository name. For: categories, issues
`organization`	No	Organization name. For: categories, issues

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. Description adds that 'issues' returns server-rendered ECharts pie charts and instructs to present them as-is, plus cache-control hint. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is verbose and repetitive; same '[INSTRUCTIONS]' and similar phrases for each action. Could be condensed to one clear workflow without duplication.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but description explains return values (counts, pie charts) and provides workflow. Lacks error handling details but sufficient for a read-only overview tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters. Description repeats action options but adds workflow context for 'categories' vs 'issues'. Does not add significant new meaning beyond schema for other parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns category-level counts or aggregated issue overview with pie charts. It distinguishes from sibling tools (e.g., codacy_issues.list, codacy_pull_requests) by focusing on high-level overviews and drill-down guidance.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit guidance on when to use each action: 'categories' for counts to drill down with codacy_issues.list, 'issues' for pie charts to identify high-impact areas. Also instructs not to recalculate pies. Clear alternatives and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codacy_pull_requestsB

Destructive

[INSTRUCTIONS] Use ONLY when the user explicitly wants to override the quality gate — this is a deliberate decision with security implications. Common mistakes: (1) Bypassing without user confirmation. (2) Bypassing for quality issues that could be fixed — suggest fixing first. This action is idempotent — calling it twice has no additional effect.

Bypass the analysis quality gate for a pull request. Allows merging even if quality standards are not met.. Select operation via the action parameter. Actions: bypass, get, list, coverage, diff, trigger_ai_review

Workflow:

'bypass': [INSTRUCTIONS] Use ONLY when the user explicitly wants to override the quality gate — this is a deliberate decision with security implications. Common mistakes: (1) Bypassing without user confirmation. (2) Bypassing for quality issues that could be fixed — suggest fixing first. This action is idempotent — calling it twice has no additional effect.

Bypass the analysis quality gate for a pull request. Allows merging even if quality standards are not met.. Requires: pullRequestNumber [DESTRUCTIVE]

'get': [INSTRUCTIONS] isUpToStandards=false means the quality gate FAILED. Investigate with codacy_issues.pr_issues and codacy_pull_requests.coverage. Common mistake: treating isUpToStandards=null as passed — null means analysis is not yet complete.

Get pull request details with quality analysis results (isUpToStandards, new/fixed issues, coverage).. Requires: pullRequestNumber

'list': [INSTRUCTIONS] Lists PRs with quality analysis status. Analysis reflects COMMITTED code only — local changes are NOT visible. Common mistake: expecting analysis to update in real-time after a push — there is processing delay. Use codacy_pull_requests.get to check if isAnalysed=true.

List pull requests in a repository with analysis status.

'coverage': Get file-level coverage data for the pull request diff.. Requires: pullRequestNumber
'diff': Get the Git diff for a pull request.. Requires: pullRequestNumber
'trigger_ai_review': [INSTRUCTIONS] This triggers NEW work — use ONLY when the user explicitly asks for an AI code review. NOT idempotent — each call dispatches a new review. Prerequisite: the PR must be analysed (isAnalysed=true). If not, suggest waiting for analysis to complete. Common mistake: triggering review on unanalysed PRs — check with codacy_pull_requests.get first.

Trigger a Codacy AI-powered code review on a pull request.. Requires: pullRequestNumber [DESTRUCTIVE] [Cache-Control: no-store]

ParametersJSON Schema

Name	Required	Description
`limit`	No	Results per page (max 100). For: list
`action`	Yes	Which operation to perform
`cursor`	No	Pagination cursor. For: list
`provider`	No	Git provider. For: bypass, get, list, coverage, diff, trigger_ai_review
`repository`	No	Repository name. For: bypass, get, list, coverage, diff, trigger_ai_review
`organization`	No	Organization name. For: bypass, get, list, coverage, diff, trigger_ai_review
`pullRequestNumber`	No	Pull request number. Required for: bypass, get, coverage, diff, trigger_ai_review

TDQS

B3.2/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description states bypass is 'idempotent' but the idempotentHint annotation is false, a direct contradiction. While the description adds useful details like processing delays, the contradiction undermines trust. Score 1 due to contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is overly verbose with repeated INSTRUCTIONS blocks and nested text. For example, the bypass action repeats the same instruction twice. Could be significantly more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description explains expected results for key actions (e.g., 'get' returns isUpToStandards, new/fixed issues, coverage). It covers prerequisites, processing delays, and common mistakes, making it fairly complete for agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters. The description adds value by linking parameters to specific actions (e.g., pullRequestNumber required for bypass, get, etc.), providing context beyond the schema's descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it manages pull request quality gates with multiple actions (bypass, get, list, etc.), distinguishing it from sibling tools like codacy_overview. However, the initial INSTRUCTIONS block clutters the core purpose, reducing clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use instructions for each action, e.g., 'Use ONLY when the user explicitly wants to override the quality gate' for bypass, and warns about common mistakes. It also explains how to interpret results (e.g., isUpToStandards). Minor deduction for overlapping instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codacy_qualityA

Read-only

[INSTRUCTIONS] Returns the full threshold configuration for a policy. Use the policyId from codacy_quality.list_policies. Thresholds define pass/fail conditions for issues, coverage, complexity, and duplication.

Get details of a specific gate policy including all thresholds.. Select operation via the action parameter. Actions: get_policy, get_settings, list_policies

Workflow:

'get_policy': [INSTRUCTIONS] Returns the full threshold configuration for a policy. Use the policyId from codacy_quality.list_policies. Thresholds define pass/fail conditions for issues, coverage, complexity, and duplication.

Get details of a specific gate policy including all thresholds.. Requires: policyId

'get_settings': [INSTRUCTIONS] Returns the quality gate configuration — thresholds for issues, coverage, complexity, and duplication. These settings determine what isUpToStandards means for PRs and commits.

Get quality settings for a repository (commit/PR/repository thresholds).

'list_policies': [INSTRUCTIONS] Gate policies are organization-level quality rules applied to repositories. Common mistake: confusing policies with repository-specific settings — policies are templates, settings are per-repo. isDefault=true means this policy applies to all repos without explicit overrides.

List gate policies for an organization. [Cache-Control: no-store]

ParametersJSON Schema

Name	Required	Description
`action`	Yes	Which operation to perform
`policyId`	No	Gate policy ID. Required for: get_policy
`provider`	No	Git provider. For: get_policy, get_settings, list_policies
`repository`	No	Repository name. For: get_settings
`organization`	No	Organization name. For: get_policy, get_settings, list_policies

TDQS

A3.6/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only, non-destructive behavior. The description adds context about thresholds and the difference between policies and settings, and mentions cache-control for list_policies. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is verbose and contains repetitive phrases (e.g., the same sentence appears for get_policy and the top-level description). It could be streamlined significantly without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequately explains each action's purpose and prerequisites. However, lacks details about return values or error handling. For a read-only tool with 5 parameters and no output schema, this is sufficient but not exceptional.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3. The description repeats what the schema already states (e.g., policyId required for get_policy) without adding new semantic information. Minimal extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool handles quality gate operations (policies, settings, listing) and distinguishes from sibling tools which cover different areas (overview, PRs, repos, security). However, the description is somewhat repetitive and could be more concise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides workflow instructions for each action (e.g., 'get_policy' requires policyId from 'list_policies') and warns against confusing policies with settings. Does not explicitly state when not to use this tool versus siblings, but the domain distinction is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codacy_repositoriesA

Destructive

[INSTRUCTIONS] Returns the overall repository health: Grade (A-F scale), coverage %, complexity, issue count. Common mistake: assuming Grade=A means zero issues — the grade is a composite score. Use codacy_issues.list for the actual issue breakdown.

Get repository details with analysis metrics (grade, coverage, complexity, issues).. Select operation via the action parameter. Actions: get, list_branches, setup

Workflow:

'get': [INSTRUCTIONS] Returns the overall repository health: Grade (A-F scale), coverage %, complexity, issue count. Common mistake: assuming Grade=A means zero issues — the grade is a composite score. Use codacy_issues.list for the actual issue breakdown.

Get repository details with analysis metrics (grade, coverage, complexity, issues).

'list_branches': [INSTRUCTIONS] Lists all branches tracked by Codacy analysis. The default branch is the one being analyzed — other branches may have limited or no analysis data.

List branches of a repository.

'setup': [INSTRUCTIONS] Use ONLY when the user explicitly wants to add a new repository for analysis. This is a multi-step action: it will (1) find the organization, (2) join it if needed, (3) find the repository, and (4) add or follow it. Common mistake: calling setup on an already-tracked repository — it will return a success message without re-adding. This action invalidates organization and repository caches.

Add or follow a repository in Codacy. This sets up analysis tracking. [DESTRUCTIVE] [Cache-Control: no-store]

ParametersJSON Schema

Name	Required	Description
`action`	Yes	Which operation to perform
`provider`	No	Git provider. For: get, list_branches, setup
`repository`	No	Repository name. For: get, list_branches, setup
`organization`	No	Organization name. For: get, list_branches, setup

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations mark destructiveHint=true. Description elaborates: setup invalidates caches, marks as [DESTRUCTIVE] [Cache-Control: no-store], and notes that Grade=A may not mean zero issues. No contradictions with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness2/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is repetitive, especially the 'get' action instructions appearing twice. It includes redundant '[INSTRUCTIONS]' tags and could be half the length without losing clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 4 parameters, no output schema, and annotations present, the description covers usage, workflow, common mistakes, and behavioral traits effectively. However, missing details about return format (e.g., data structure) slightly reduce completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and describes each parameter concisely. The description adds value by explaining the workflow for each action and the meaning of 'get' output, but does not deeply elaborate on parameter syntax beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the tool returns repository health metrics (grade, coverage, complexity, issues) and lists three distinct actions (get, list_branches, setup). It distinguishes from sibling tools by focusing on repository-level analysis versus overviews or pull requests.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use setup ('only when user wants to add a new repository'), warns against calling setup on already-tracked repos, and directs to codacy_issues.list for actual issue breakdown, providing clear alternative usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

codacy_securityA

Destructive

Get the security dashboard summary for a repository.. Select operation via the action parameter. Actions: dashboard, ignore, ossf_scorecard, sbom_search, search_org, search_repo

Workflow:

'dashboard': Get the security dashboard summary for a repository.
'ignore': [INSTRUCTIONS] Use when the user explicitly wants to mark a security finding as ignored. Always provide a reason: FalsePositive, WontFix, or NotRelevant. Common mistakes: (1) Do NOT invent reasons. (2) Ignoring without user confirmation — this is a security decision, always confirm. This action is idempotent — calling it twice with the same srmItemId has no additional effect.

Ignore or unignore a security finding.. Requires: srmItemId, reason [DESTRUCTIVE]

'ossf_scorecard': [INSTRUCTIONS] Accepts either a repository URL (e.g., https://github.com/org/repo) or a purl (e.g., maven:ch.qos.logback:logback-classic:1.2.3). At least one is required. Common mistake: not providing either url or purl — the API requires at least one identifier. Use the purl from SBOM search results.

Get the OSSF Scorecard for a repository or package. Returns security posture score.

'sbom_search': [INSTRUCTIONS] Supply chain security investigation — search SBOM dependencies by name, vulnerability severity, or risk category. Common mistakes: (1) Confusing SBOM search with security findings — SBOM shows dependencies, use codacy_security.search_repo for code-level findings. (2) Risk categories: Forbidden, Risky, Normal — do NOT invent categories. Use purl (Package URL) as the universal identifier for cross-referencing with OSSF Scorecard.

Search SBOM dependencies across the organization. Find vulnerable packages by name, severity, or risk category.

'search_org': [INSTRUCTIONS] Cross-repository security overview at the organization level. For repository-specific findings, use codacy_security.search_repo instead. Scan types: SAST, SCA, Secrets, IaC, CICD (repo-level). DAST and PenTesting are organization-level only. Common mistakes: (1) Using this for code quality issues — use codacy_issues instead. (2) Status values: OnTrack, DueSoon, Overdue (open), ClosedOnTime, ClosedLate, Ignored (closed) — do NOT invent statuses.

Search organization-level security findings across all repositories.

'search_repo': [INSTRUCTIONS] Repository-scoped security search. Uses the organization-level API filtered by this repository. Scan types available at repo level: SAST, SCA, Secrets, IaC, CICD. For DAST and PenTesting, use codacy_security.search_org instead. Common mistake: using DAST or PenTesting scan types here — those are organization-level only.

Search security findings within a specific repository. [Cache-Control: no-store]

ParametersJSON Schema

Name	Required	Description
`url`	No	Repository URL (e.g., https://github.com/org/repo). For: ossf_scorecard
`purl`	No	Package URL in purl format (e.g., maven:ch.qos.logback:logback-classic:1.2.3). For: ossf_scorecard
`text`	No	Search by dependency name or package URL. For: sbom_search
`limit`	No	Results per page (max 100). For: sbom_search, search_org, search_repo
`action`	Yes	Which operation to perform
`cursor`	No	Pagination cursor. For: sbom_search, search_org, search_repo
`reason`	No	Reason for ignoring. Required for: ignore
`status`	No	Filter by status (OnTrack, DueSoon, Overdue, ClosedOnTime, ClosedLate, Ignored). For: search_org, search_repo
`comment`	No	Optional explanation comment. For: ignore
`category`	No	Filter by security category (e.g., Injection, XSS, CSRF). For: search_org, search_repo
`priority`	No	Filter by priority. For: search_org, search_repo
`provider`	No	Git provider. For: dashboard, ignore, sbom_search, search_org, search_repo
`scanType`	No	Filter by scan type. For: search_org, search_repo
`srmItemId`	No	SRM item identifier. Required for: ignore
`repository`	No	Repository name. For: dashboard, search_repo
`organization`	No	Organization name. For: dashboard, ignore, sbom_search, search_org, search_repo
`riskCategory`	No	Filter by risk classification. For: sbom_search
`findingSeverity`	No	Filter by vulnerability severity. For: sbom_search

TDQS

A4.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds useful behavioral context (e.g., idempotency of 'ignore', cache-control for search_repo, destructive nature of ignore). However, it contradicts the annotation 'idempotentHint: false' by stating that the ignore action is idempotent. This reduces reliability.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with headers for each action, bullet points, and front-loaded purpose. While lengthy due to the complexity of six actions, it remains organized and avoids unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the 18 parameters, no output schema, and rich annotations, the description covers all necessary context: action-specific usage, parameter requirements, common mistakes, alternatives, and behavioral notes. It is thorough for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 100% schema coverage, the description enhances parameter understanding by explaining which parameters apply to which actions, providing common mistakes, and clarifying enumerated values (e.g., status values, risk categories).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it provides security dashboard summary and lists six specific actions, each with a clear purpose. It distinguishes itself from sibling tools (codacy_overview, codacy_quality, etc.) by focusing exclusively on security operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit instructions for each action, including when to use alternatives (e.g., using search_org for DAST/PenTesting instead of search_repo) and common mistakes to avoid. It also differentiates from other tools like codacy_issues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

5 tool updatesv1.0.0Jul 27, 2026
- First observedcodacy_overview
- First observedcodacy_pull_requests
- First observedcodacy_quality
- First observedcodacy_repositories
- First observedcodacy_security

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-07-27 10:34 across 5 tools

Disambiguation5/5

Each tool targets a distinct area: overview, pull requests, quality policies, repository metrics, and security. There is no functional overlap; agents can clearly differentiate them.

Naming Consistency5/5

All tool names follow the pattern 'codacy_<noun>', using lowercase with underscores. The naming is uniform and predictable.

Tool Count5/5

With 5 tools, the server covers the core aspects of code quality and security analysis without being excessive or insufficient. Each tool earns its place.

Completeness3/5

The tool set provides overviews, PR analysis, quality settings, repository metrics, and security. However, it lacks a dedicated tool for listing and managing individual code issues (the instructions reference a missing 'codacy_issues.list'), which is a notable gap for detailed investigation.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
mcp COAuth
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
216
saidsef-mcp-github-pr-issue-analyser
ai.smithery
A Model Context Protocol (MCP) application for automated GitHub PR analysis and issue management.…
Version Control Developer Tools Project Management
26
mcp-serverOAuth
com.niftypm
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Project Management Communication File Systems
2

Related MCP Servers

WithSeismic MCP
Agent Orchestration Developer Tools Autonomous Agents
dougwithseismic
A
license
Not graded
quality
D
maintenance
A TypeScript implementation of a Model Context Protocol server that provides a frictionless framework for developers to build and deploy AI tools and prompts, focusing on developer experience with zero boilerplate and automatic tool registration.
Updated a year ago (2025-03-26 11:29 UTC)
681 npm
14
MIT
CodeAlive MCPofficial
Code Analysis RAG Systems Developer Tools
CodeAlive-AI
A
license
Not graded
quality
A
maintenance
A Model Context Protocol server that enhances AI agents by providing deep semantic understanding of codebases, enabling more intelligent interactions through advanced code search and contextual awareness.
Updated 5 days ago (2026-09-12 17:37 UTC)
90
MIT
xmcp Application
Developer Tools Code Execution
SumitNawathe
F
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server template designed for building structured tools, prompts, and resources with built-in support for HTTP and STDIO transports. It provides a standardized framework for developers to create and deploy AI-driven services using TypeScript and Zod schema validation.
Updated 6 months ago (2026-03-17 03:05 UTC)
7 npm
-
@verlon-ai/mcpofficial
AI & Machine Learning Observability
verlon-ai
A
license
A
quality
B
maintenance
Model Context Protocol server for Verlon AI that exposes gates, logs, recommendations, and experiments as MCP tools, enabling coding agents to inspect and manage AI infrastructure natively.
Updated 4 days ago (2026-09-13 05:04 UTC)
5
100 npm
MIT

Codacy MCP Server — Vurb.ts Edition

11 Tools - 44 actions available on-demand

3 Prompts MCP prompts — code-review, security-audit, repo-health

🤖 Zero lines of human code.

📐 Designed for agents, not for humans.

Why Vurb.ts?

Capability Matrix

Grouped Tool Exposition — Solving Context Explosion

The Problem

The Solution: toolExposition: 'grouped'

How the LLM Navigates

Context Window Impact

Developer Experience — Side by Side

🔒 What Reaches the LLM — The Security Gap

Architecture Comparison

Metrics (verified)

Tool Actions (44)

codacy_organizations (2)

codacy_repositories (3)

codacy_issues (7)

codacy_security (6)

codacy_tools (6)

codacy_files (4)

codacy_pull_requests (6)

codacy_commits (3)

codacy_overview (2)

codacy_quality (3)

codacy_cli (2)

Setup

Requirements

Configuration

Development

Project Structure

Usage (MCP stdio)

Cursor / Windsurf / Claude Desktop

VS Code (Copilot)

Get your token

Build & run

License

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

CodeAlive MCPofficial

@verlon-ai/mcpofficial

The Solution: `toolExposition: 'grouped'`