> ## Documentation Index > Fetch the complete documentation index at: https://docs.corgea.app/llms.txt > Use this file to discover all available pages before exploring further. # Model Context Protocol (MCP) > Connect AI assistants to Corgea using the Model Context Protocol Corgea supports the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), allowing AI assistants like Claude to directly interact with your security scans, issues, and policies. MCP enables AI models to understand your security context and provide more relevant assistance. ## What is MCP? The Model Context Protocol is an open standard that enables AI models to securely connect to external data sources and tools. With Corgea's MCP integration, AI assistants can: * Query your security scan results * Retrieve vulnerability details * List and filter security issues * List and filter code quality issues * Access SCA, IaC, and dependency inventory data * Export the dependency inventory as CSV * Check blocking rules and policies ## Getting Started ### Prerequisites * A Corgea API token, from **Settings → Automation → [API token](https://www.corgea.app/settings/integrations/api-token/)** * An MCP-compatible client (e.g., Claude Desktop, Continue, or any MCP client) ### Connection Details **MCP Server URL:** ``` https://www.corgea.app/mcp ``` Or for single-tenant deployments: ``` https://.corgea.app/mcp ``` **Authentication:** All MCP requests require authentication using your Corgea API token in the `CORGEA-TOKEN` header. Corgea supports stateless MCP requests over POST with JSON responses. Standalone server-sent event (SSE) streams are not supported. ## Available Tools Corgea's MCP server provides the following tools for AI assistants: ### get\_scan\_info Get detailed information about a specific SAST scan. **Parameters:** * `scan_id` (string, required): The unique identifier of the scan **Returns:** Detailed scan information including status, findings count, scan date, and repository information. **Example:** ```json theme={null} { "scan_id": "abc123", "status": "completed", "created_at": "2024-11-01T10:30:00Z", "findings_count": 15, "project": "my-project", "repository": "https://github.com/myorg/myrepo" } ``` *** ### get\_issue\_info Get detailed information about a specific security issue. **Parameters:** * `issue_id` (string, required): The unique identifier of the issue * `include_reachability` (boolean, optional): Include endpoint reachability details for the issue **Returns:** Comprehensive issue details including vulnerability type, severity, location, fix recommendations, remediation status, and optional endpoint reachability details. **Example:** ```json theme={null} { "issue_id": "issue-456", "title": "SQL Injection", "severity": "high", "file": "src/database.py", "line": 42, "description": "User input not properly sanitized", "fix_available": true } ``` *** ### get\_sca\_issue\_info Get detailed information about a specific Software Composition Analysis (SCA) issue. **Parameters:** * `issue_id` (string, required): The unique identifier of the SCA issue **Returns:** SCA issue details including package, severity, CVE, fix version, file location, and dependency reachability analysis. **Example:** ```json theme={null} { "status": "ok", "issue": { "id": "sca-789", "package": { "name": "lodash", "version": "4.17.15", "ecosystem": "npm", "fix_version": "4.17.21" }, "cve": "CVE-2021-23337", "severity": "high", "reachability": { "status": "vulnerable_usage_reachable", "description": "Vulnerable function is reachable from application code", "usages": [] } } } ``` *** ### list\_security\_issues List security issues with optional filtering. **Parameters:** * `scan_id` (string, optional): Filter issues by scan ID * `project` (string, optional): Filter issues by project name * `repo` (string, optional): Filter issues by repository URL * `include_reachability` (boolean, optional): Include endpoint reachability summary for each issue **Returns:** List of security issues matching the specified filters. **Example:** ```json theme={null} { "status": "ok", "count": 25, "issues": [ { "id": "issue-123", "title": "Cross-Site Scripting (XSS)", "severity": "medium", "status": "open" } ] } ``` *** ### list\_code\_quality\_issues List code quality findings separately from security issues, with optional filtering. **Parameters:** * `scan_id` (string, optional): Filter issues by scan ID * `project` (string, optional): Filter issues by project name * `repo` (string, optional): Filter issues by repository URL * `filters` (object, optional): Filter by `urgency`, `status`, `confidence`, `language`, `file_path`, `classification`, `sla_status`, `branch`, `show_false_positives`, or `sort_by` * `page` (integer, optional): Page number * `page_size` (integer, optional): Number of results per page, up to 50 The `classification` field contains the code quality label, such as `Maintainability`, rather than a CWE. False positives are excluded by default. **Returns:** Only code quality issues matching the specified scope and filters. *** ### list\_sca\_security\_issues List Software Composition Analysis (SCA) security issues with optional filtering. **Parameters:** * `scan_id` (string, optional): Filter issues by scan ID * `project` (string, optional): Filter issues by project name * `repo` (string, optional): Filter issues by repository URL * `filters` (object, optional): Filter by fields such as `severity`, `package`, `ecosystem`, `cve`, `path`, `has_fix`, `branch`, `reachability`, or `sort_by` * `include_reachability` (boolean, optional): Include dependency reachability status and description for each SCA issue Supported `reachability` filter values are `not_direct_dependency`, `pending`, `vulnerable_usage_reachable`, `vulnerable_usage_unreachable`, and `dead_dependency`. **Returns:** List of SCA issues including vulnerable dependencies, CVEs, and version information. **Example:** ```json theme={null} { "status": "ok", "count": 12, "sca_issues": [ { "id": "sca-789", "package": "lodash", "current_version": "4.17.15", "fixed_version": "4.17.21", "cve": "CVE-2021-23337", "severity": "high" } ] } ``` *** ### list\_iac\_security\_issues List Infrastructure-as-Code (IaC) security issues with optional filtering. **Parameters:** * `scan_id` (string, optional): Filter issues by scan ID * `project` (string, optional): Filter issues by project name * `repo` (string, optional): Filter issues by repository URL * `filters` (object, optional): Filter by `severity`, `provider`, `service`, `iac_type`, `rule_id`, `avd_id`, `path`, `search`, `sort_by`, or `branch` * `page` (integer, optional): Page number * `page_size` (integer, optional): Number of results per page, up to 50 **Returns:** List of IaC issues including severity, affected service, rule identifiers, file location, and scan context. **Example:** ```json theme={null} { "status": "ok", "page": 1, "total_pages": 1, "total_issues": 1, "issues": [ { "id": "11111111-1111-1111-1111-111111111111", "title": "Public S3 bucket", "severity": "HIGH", "provider": "aws", "service": "s3", "iac_type": "terraform", "location": { "path": "infra/main.tf", "start_line": 10 } } ] } ``` *** ### list\_dependencies List software dependencies discovered during a scan with optional filtering. **Parameters:** * `scan_id` (string, optional): Filter dependencies by scan ID * `project` (string, optional): Filter dependencies by project name * `repo` (string, optional): Filter dependencies by repository URL * `filters` (object, optional): Filter by `name`, `version`, `type`, `path`, `purl`, `license`, `dep_type`, `search`, `sort_by`, or `branch` * `page` (integer, optional): Page number * `page_size` (integer, optional): Number of results per page, up to 50 **Returns:** List of dependencies including package name, version, package URL, license data, dependency relationship, and scan context. **Example:** ```json theme={null} { "status": "ok", "page": 1, "total_pages": 1, "total_dependencies": 1, "dependencies": [ { "id": "22222222-2222-2222-2222-222222222222", "name": "django", "version": "4.2.0", "type": "pypi", "purl": "pkg:pypi/django@4.2.0", "path": "requirements.txt", "licenses": ["BSD-3-Clause"], "is_direct": true } ] } ``` *** ### export\_dependencies\_csv Generate a link for downloading a project's dependency findings as a CSV file. **Parameters:** * `project` (string, required): Project name or ID * `scan_id` (string, optional): Export a specific scan; defaults to the latest scan * `branch` (string, optional): Filter dependencies by branch name * `ecosystem` (string, optional): Filter by ecosystem, such as `pypi`, `npm`, or `maven` * `severity` (string, optional): Filter by severity — `critical`, `high`, `medium`, or `low` * `reachability` (string, optional): Filter by reachability — `reachable`, `unreachable`, `unused`, or `analyzing` * `dependency_type` (string, optional): Filter by dependency relationship — `direct`, `transitive`, `dev`, or `optional` * `search` (string, optional): Filter by package name **Returns:** A `download_url` to hand to the user, not the CSV rows themselves. Use `list_dependencies` when the assistant needs the data to reason over. The link resolves the same export as the download icon on the **Dependencies** tab, so it requires the **View SCA Issue** permission and produces the columns described in [Issue Export](/issue_export#dependency-exports). **Example:** ```json theme={null} { "download_url": "https://www.corgea.app/project/my-project/sca-findings/export/?urgency=critical", "message": "CSV export URL generated for project 'my-project'. Share this link with the user to download the file." } ``` *** ### list\_scans List all SAST scans with optional filtering. **Parameters:** * `project` (string, optional): Filter scans by project name * `repo` (string, optional): Filter scans by repository URL substring * `branch` (string, optional): Filter scans by exact branch name * `pull_request_id` (string, optional): Filter scans by exact pull request or merge request identifier * `sha` (string, optional): Filter scans by exact commit SHA * `metadata_key` (string, optional): Filter scans that contain this metadata key; combine with `metadata_value` to match an exact key and value * `metadata_value` (string, optional): Match an exact value for `metadata_key`, or search across scan metadata when used alone * `page` (integer, optional): Page number * `page_size` (integer, optional): Number of scans per page **Returns:** List of scans with basic information including scan ID, date, status, and findings count. **Example:** ```json theme={null} { "status": "ok", "count": 50, "scans": [ { "id": "scan-001", "project": "web-app", "created_at": "2024-11-01T09:00:00Z", "status": "completed", "findings": 8 } ] } ``` *** ### get\_blocking\_rules Get all blocking rules configured for your organization. **Parameters:** None **Returns:** List of blocking rules that prevent deployments based on security policies. **Example:** ```json theme={null} { "status": "ok", "rules": [ { "id": "rule-1", "name": "Block Critical Vulnerabilities", "condition": "severity >= critical", "action": "block", "enabled": true } ] } ``` ## Setting Up MCP Clients ### Claude Desktop Add Corgea to your Claude Desktop configuration: 1. Open Claude Desktop settings 2. Navigate to the "Developer" section 3. Edit your MCP configuration file 4. Add the Corgea MCP server: ```json theme={null} { "mcpServers": { "corgea": { "command": "npx", "args": [ "-y", "mcp-remote", "https://www.corgea.app/mcp", "--header", "CORGEA-TOKEN:${CORGEA_TOKEN}" ], "env": { "CORGEA_TOKEN": "your_api_token_here" } } } } ``` Claude Desktop does not substitute variables in this file. `${CORGEA_TOKEN}` is resolved by `mcp-remote`, which reads it from the environment the `env` block gives it, so the token has to be written there. Leave out the space after `CORGEA-TOKEN:` — Claude Desktop on Windows does not escape spaces inside `args`, and the header arrives mangled. 5. Restart Claude Desktop for the changes to take effect ### Cursor IDE Add Corgea to your Cursor MCP configuration: 1. Open Cursor Settings (Cmd/Ctrl + Shift + J) 2. Navigate to "Cursor Settings" → "Models" → "MCP" 3. Or directly edit your MCP settings file at: * **macOS/Linux**: `~/.cursor/mcp.json` * **Windows**: `%APPDATA%\Cursor\User\mcp.json` 4. Add the Corgea MCP server: ```json theme={null} { "mcpServers": { "corgea": { "command": "npx", "args": [ "-y", "mcp-remote", "https://www.corgea.app/mcp", "--transport", "http-only", "--header", "CORGEA-TOKEN:${env:CORGEA_TOKEN}" ] } } } ``` Cursor resolves `${env:NAME}` itself, so the token can live in your environment instead of the file. The spelling is Cursor's own: `${env:CORGEA_TOKEN}` in Claude Desktop resolves to nothing and the header goes out empty. As above, keep the space out after `CORGEA-TOKEN:`. Cursor reads the variable from its own process environment. `export CORGEA_TOKEN=...` in a terminal reaches only that shell and its children, so a Cursor started from the Dock, Start menu or a desktop entry never sees it and the header goes out empty. Set it where the desktop session will find it, then restart Cursor: * **macOS**: `launchctl setenv CORGEA_TOKEN `, which lasts until you reboot. * **Windows**: `setx CORGEA_TOKEN `, which persists for your user account. * **Linux**: put `CORGEA_TOKEN=` in `~/.config/environment.d/corgea.conf` and log back in. Launching Cursor from a shell that already has the variable exported works anywhere, and is the quickest way to confirm this is the problem. An empty `CORGEA-TOKEN` header and a 401 is the symptom. The `mcp-remote` bridge is required here, not a convenience. Cursor's built-in `"url"` transport connects and then opens a server-sent events stream, which this server does not support, so the connection fails with `Failed to open SSE stream: Not Acceptable` and no tools appear. **Alternative Configuration (Direct HTTP):** For a client that posts JSON directly and does not open a standalone SSE stream: ```json theme={null} { "mcpServers": { "corgea": { "url": "https://www.corgea.app/mcp", "headers": { "CORGEA-TOKEN": "your_api_token_here" } } } } ``` Not all clients advertising HTTP transport qualify. Cursor is one that does not — use the `mcp-remote` configuration above there instead. A 406 or `Not Acceptable` on connect means the client is trying to open the SSE stream. ### Continue IDE Extension Add Corgea to your Continue configuration: ```json theme={null} { "contextProviders": [ { "name": "corgea", "params": { "serverUrl": "https://www.corgea.app/mcp", "headers": { "CORGEA-TOKEN": "your_api_token_here" } } } ] } ``` ## Use Cases ### Security-Aware Code Review Connect your AI assistant to Corgea and ask questions like: * "What are the critical security issues in my last scan?" * "Show me all SQL injection vulnerabilities in the authentication module" * "Are there any high-severity SCA issues in my dependencies?" ### Vulnerability Analysis Let AI help you understand and prioritize vulnerabilities: * "Explain the security issue in issue-456 and suggest how to fix it" * "Which vulnerabilities should I fix first based on severity and exploitability?" * "What are the blocking rules that would prevent this deployment?" ### Automated Remediation Planning Use AI to plan security fixes: * "Create a remediation plan for all high-severity issues in scan-123" * "What dependencies need to be updated to fix SCA issues?" * "Generate a report of all open security issues grouped by file" ## Best Practices * Never commit your API token to version control * Rotate tokens periodically * Use environment variables or secure secret managers * Revoke tokens immediately if compromised * Use project, repo, branch, and pull request filters to narrow results * Start with specific scans when debugging * Filter by severity when prioritizing work * Request only the data you need * Use specific issue/scan IDs when possible * Cache results when appropriate * Respect rate limits ## Authentication All MCP tool calls require a valid Corgea API token passed in the `CORGEA-TOKEN` header. **Getting Your Token:** 1. Log in to your Corgea account 2. Go to **Settings → Automation → API token** 3. Generate a new API token 4. Copy the token and add it to your MCP client configuration Keep your API token secure. Anyone with access to your token can query your security data through the MCP interface. Where the client can read the token from your environment, prefer that over writing it into the configuration file, and keep any file holding it out of version control. There is no shared syntax for this: Cursor uses `${env:NAME}`, Claude Code uses `${NAME}`, and Claude Desktop has none of its own. ## Response Format All MCP tool responses follow the standard Corgea API response format: **Success Response:** ```json theme={null} { "status": "ok", "data": { } } ``` **Error Response:** ```json theme={null} { "status": "error", "message": "Description of the error", "error": "Detailed error information" } ``` ## Rate Limits MCP requests are subject to the same rate limits as standard API requests: * 100 requests per minute per token * 1000 requests per hour per token If you exceed rate limits, you'll receive a `429 Too Many Requests` response. ## Troubleshooting ### Connection Issues **Problem:** Cannot connect to MCP server **Solutions:** * Verify your API token is valid using the `/verify` endpoint * Check that the `CORGEA-TOKEN` header is correctly configured * Ensure your network allows HTTPS connections to corgea.app ### Authentication Errors **Problem:** Receiving 401 Unauthorized responses **Solutions:** * Verify your API token hasn't expired * Check that the token is passed in the `CORGEA-TOKEN` header (not Authorization) * Ensure your token has the necessary permissions ### Empty Results **Problem:** Queries return no data **Solutions:** * Verify data exists in your Corgea account * Check filter parameters (scan\_id, project, repo, branch, pull\_request\_id) are correct * Ensure you're querying the correct environment (multi-tenant vs single-tenant) ## Support Learn more about the Corgea API Get help from the Corgea community Learn about API authentication Read the official MCP documentation ## Next Steps 1. **Get your API token** from **Settings → Automation → API token** 2. **Configure your MCP client** with the Corgea server URL and token 3. **Test the connection** by asking your AI assistant about your scans 4. **Explore use cases** like security analysis and vulnerability remediation Start integrating Corgea's security intelligence into your AI-powered development workflow today!