MCP Tools Reference - ZeroPath Documentation

The MCP server exposes tools that map to ZeroPath’s REST V2 API. Tools are loaded from ZeroPath’s MCP manifest at startup, so your AI assistant always has access to current capabilities.

Issues

10 tools — list, triage, investigate, update status and severity

Scans

2 tools — list scan history, get scan details

Repositories

1 tool — list repositories with filtering

Code Inspection

3 tools — search, read, and list files in connected repositories

Rules

5 tools — full CRUD for custom security rules

Organization Scoping

Every tool accepts organizationId. The MCP server handles this automatically:

If ZEROPATH_ORG_ID is set, the server injects it into every request — you never need to pass it yourself.
If ZEROPATH_ORG_ID is not set, you must pass organizationId explicitly. Most tools require it at the API level; a few (like issues.list) can resolve org context from your auth session.

Set ZEROPATH_ORG_ID during installation to avoid passing organizationId in every call.

Issue Tools

issues.list

List and filter security issues. Uses offset-based pagination via offset and limit.

Parameter	Type	Required	Description
`offset`	integer	No	Starting index (default: 0)
`limit`	integer	No	Results per page (default: 25, max: 100)
`statuses`	string[]	No	Filter by status: `PENDING_REVIEW`, `REVIEWING`, `PATCHING`, `RESOLVED`, `BACKLOG`, `INFORMATIONAL`, `NON_EXPLOITABLE`, `FALSE_POSITIVE`, `ACCEPTED_RISK`
`scoreLevels`	string[]	No	Filter by severity level: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO`
`scoreRange`	object	No	Filter by numeric score range: `{ min: number, max: number }` (0–100)
`searchQuery`	string	No	Free-text search across issue titles and descriptions
`scanId`	string	No	Filter to issues from a specific scan
`languages`	string[]	No	Filter by programming language
`vulnerabilityClasses`	string[]	No	Filter by vulnerability class (e.g., `SQL Injection`)
`codeScanTypes`	string[]	No	Filter by scan type
`detectionTypes`	string[]	No	Filter by detection category
`repositoryBranches`	object[]	No	Filter to specific repositories and branches
`projectId`	string	No	Filter to a specific project
`sortBy`	string	No	Sort field: `createdAt`, `score`, `title`, `repository`, `class`, `file`, `patch`
`sortOrder`	string	No	`asc` or `desc`
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "offset": 0,
  "limit": 25,
  "statuses": ["PENDING_REVIEW"],
  "scoreLevels": ["CRITICAL", "HIGH"],
  "sortBy": "score",
  "sortOrder": "desc"
}

issues.archive

Archive issues to remove them from active views.

Parameter	Type	Required	Description
`issueIds`	string[]	Yes	Issue IDs to archive
`reason`	string	No	Reason for archiving
`organizationId`	string	Yes	Injected from `ZEROPATH_ORG_ID`; pass explicitly if not configured

{
  "issueIds": ["issue_123", "issue_456"],
  "reason": "Confirmed duplicate"
}

issues.unarchive

Restore archived issues back to active views.

Parameter	Type	Required	Description
`issueIds`	string[]	Yes	Issue IDs to unarchive
`organizationId`	string	Yes	Injected from `ZEROPATH_ORG_ID`; pass explicitly if not configured

{
  "issueIds": ["issue_123"]
}

issues.markFalsePositive

Mark issues as false positives. Removes them from active review.

Parameter	Type	Required	Description
`issueIds`	string[]	Yes	Issue IDs to mark
`reason`	string	No	Reason for the determination
`organizationId`	string	Yes	Injected from `ZEROPATH_ORG_ID`; pass explicitly if not configured

{
  "issueIds": ["issue_789"],
  "reason": "Input is sanitized by middleware"
}

issues.markTruePositive

Confirm issues as true positives.

Parameter	Type	Required	Description
`issueIds`	string[]	Yes	Issue IDs to confirm
`reason`	string	No	Reason for confirmation
`organizationId`	string	Yes	Injected from `ZEROPATH_ORG_ID`; pass explicitly if not configured

{
  "issueIds": ["issue_101", "issue_102"]
}

issues.updateStatus

Update the workflow status of one or more issues.

Parameter	Type	Required	Description
`issueIds`	string[]	Yes	Issue IDs to update
`issueStatus`	string	Yes	`PENDING_REVIEW`, `REVIEWING`, `PATCHING`, `RESOLVED`, `BACKLOG`, or `INFORMATIONAL`
`reason`	string	No	Reason for the status change
`organizationId`	string	Yes	Injected from `ZEROPATH_ORG_ID`; pass explicitly if not configured

The field name is issueStatus, not status. Using the wrong field name will cause a validation error.

{
  "issueIds": ["issue_123"],
  "issueStatus": "RESOLVED",
  "reason": "Fixed in PR #456"
}

issues.updateSeverity

Update the severity score of a single issue.

Parameter	Type	Required	Description
`issueId`	string	Yes	Single issue ID (not an array)
`severity`	number	Yes	Score from 0 to 10 (supports one decimal place)
`reason`	string	No	Reason for the severity change
`organizationId`	string	Yes	Injected from `ZEROPATH_ORG_ID`; pass explicitly if not configured

This tool takes a single issueId (string), not issueIds (array). The severity field is a number between 0 and 10, not a string enum.

{
  "issueId": "issue_123",
  "severity": 8.5,
  "reason": "Upgraded after confirming public exposure"
}

issues.requestInvestigation

Request an on-demand investigation of a finding using larger AI models for higher-confidence validation.

Parameter	Type	Required	Description
`issueId`	string	Yes	Issue ID to investigate
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "issueId": "issue_123"
}

If an investigation is already in progress for the issue, the response returns the existing investigation with "status": "already_pending" instead of creating a duplicate.

issues.requestBulkInvestigation

Request investigations for multiple issues at once.

Parameter	Type	Required	Description
`issueIds`	string[]	Yes	Issue IDs to investigate
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "issueIds": ["issue_123", "issue_456", "issue_789"]
}

Issues that already have a pending or in-progress investigation are skipped. Issues that do not belong to your organization are counted as unauthorized.

issues.getInvestigationStatus

Get the latest investigation result for an issue.

Parameter	Type	Required	Description
`issueId`	string	Yes	Issue ID
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "issueId": "issue_123"
}

Returns null if no investigation has been requested for the issue. The status field can be PENDING, PROCESSING, COMPLETED, or FAILED.

Scan Tools

scans.list

List scans with cursor-based pagination. Pass the nextCursor from a previous response to paginate forward.

Parameter	Type	Required	Description
`cursor`	object	No	Cursor from previous response: `{ createdAt: string, id: string }`
`limit`	number	No	Results per page (default: 20, max: 100)
`repositoryIds`	string[]	No	Filter to specific repositories
`scanTypes`	string[]	No	`FullScan`, `PrScan` (defaults to both)
`searchQuery`	string	No	Search by scan name
`projectId`	string	No	Filter by project ID
`scoreRange`	object	No	Filter by vulnerability score: `{ min: number, max: number }` (0–100)
`showEphemeral`	boolean	No	Include CLI/ephemeral scans (default: false)
`getCounts`	boolean	No	Include vulnerability counts (default: true)
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "limit": 10,
  "repositoryIds": ["repo_123"],
  "scanTypes": ["FullScan"]
}

scans.get

Get details for a specific scan.

Parameter	Type	Required	Description
`scanId`	string	Yes	Scan ID
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "scanId": "scan_abc123"
}

Repository Tools

repositories.list

List repositories with cursor-based pagination (string cursor).

Parameter	Type	Required	Description
`cursor`	string	No	Cursor from previous response `nextCursor`
`limit`	integer	No	Results per page (default: 20, max: 100)
`sortBy`	string	No	`name` or `issues` (default: `name`)
`sortDirection`	string	No	`asc` or `desc` (default: `asc`)
`getCounts`	boolean	No	Include issue counts (default: true, may impact performance)
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "limit": 50,
  "sortBy": "issues",
  "sortDirection": "desc",
  "getCounts": true
}

Code Inspection Tools

These tools allow you to browse and search source code directly in connected GitHub and GitLab repositories without cloning.

code.search

Search for code within a repository.

Parameter	Type	Required	Description
`repositoryId`	string	Yes	Repository ID to search in
`query`	string	Yes	Search query (1–512 characters)
`ref`	string	No	Git ref (branch/tag/commit). GitLab only — GitHub always searches the default branch
`pathPrefix`	string	No	Restrict results to a directory subtree
`limit`	integer	No	Max results (default: 10, max: 50)
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "repositoryId": "repo_123",
  "query": "password",
  "pathPrefix": "src/auth",
  "limit": 5
}

code.read

Read the contents of a file in a repository.

Parameter	Type	Required	Description
`repositoryId`	string	Yes	Repository ID
`path`	string	Yes	File path within the repository
`ref`	string	No	Git ref (branch/tag/commit)
`startLine`	integer	No	First line to return (1-based)
`endLine`	integer	No	Last line to return (must be >= startLine)
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "repositoryId": "repo_123",
  "path": "src/auth/login.ts",
  "startLine": 40,
  "endLine": 50
}

Responses are capped at 1,000 lines and 200 KB. The truncatedByLineRange and truncatedByByteLimit flags indicate whether the response was truncated.

code.listFiles

List files and directories within a repository path.

Parameter	Type	Required	Description
`repositoryId`	string	Yes	Repository ID
`path`	string	No	Directory path (defaults to repository root)
`ref`	string	No	Git ref (branch/tag/commit)
`cursor`	string	No	Pagination cursor (GitLab only)
`limit`	integer	No	Max results (default: 100, max: 200)
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "repositoryId": "repo_123",
  "path": "src/auth"
}

Code inspection is currently supported for GitHub and GitLab repositories. Bitbucket, generic Git, and uploaded repositories are not yet supported.

Rule Tools

rules.list

List custom security rules. Uses offset-based pagination.

Parameter	Type	Required	Description
`offset`	integer	No	Starting index (default: 0)
`limit`	integer	No	Results per page (default: 20, max: 100)
`repositoryId`	string	No	Filter rules by repository
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "offset": 0,
  "limit": 25
}

rules.get

Get details for a specific rule, including associated repository names.

Parameter	Type	Required	Description
`ruleId`	string	Yes	Rule ID
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "ruleId": "rule_xyz789"
}

rules.create

Create a custom security rule.

Parameter	Type	Required	Description
`name`	string	Yes	Rule name
`rule`	string	Yes	Natural language rule definition
`globPattern`	string	No	File pattern (default: `*/`)
`sourceTypes`	string[]	No	`HTTP_HANDLER`, `FILE_HANDLER`, `STDIN_HANDLER`, `BROWSER_DATA`, `WEBSOCKET`, `SOCKET`, `CLI_ARGUMENT`, `MOBILE_INPUTS`
`repositoryIds`	string[]	No	Limit to specific repositories
`tagIds`	string[]	No	Tag IDs to associate with the rule
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "name": "Detect unsafe eval",
  "rule": "Detect any use of eval() on user input",
  "globPattern": "**/*.{js,ts}",
  "sourceTypes": ["HTTP_HANDLER", "FILE_HANDLER"],
  "repositoryIds": ["repo_123"],
  "tagIds": ["tag_1"]
}

rules.update

Update an existing rule. Only the fields you include will be modified.

Parameter	Type	Required	Description
`ruleId`	string	Yes	Rule ID to update
`name`	string	No	Updated name
`rule`	string	No	Updated definition
`globPattern`	string	No	Updated file pattern
`sourceTypes`	string[]	No	Updated source types
`repositoryIds`	string[]	No	Updated repository scope
`tagIds`	string[]	No	Updated tag associations
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "ruleId": "rule_xyz789",
  "name": "Detect unsafe eval (updated)",
  "globPattern": "**/*.{js,ts,jsx,tsx}"
}

rules.delete

Delete a custom rule.

Parameter	Type	Required	Description
`ruleId`	string	Yes	Rule ID to delete
`organizationId`	string	No	Injected from `ZEROPATH_ORG_ID` when configured

{
  "ruleId": "rule_xyz789"
}

Common Workflows

Triage new issues

List pending issues — call issues.list with statuses: ["PENDING_REVIEW"] sorted by score descending.
Review each issue — ask your AI assistant to summarize the vulnerability and affected code.
Classify — use issues.markTruePositive or issues.markFalsePositive with a reason.
Update status — move confirmed issues to REVIEWING or PATCHING with issues.updateStatus.
Adjust severity — if the auto-assigned score doesn’t match your assessment, use issues.updateSeverity with a value from 0 to 10.

Create custom rules

List existing rules — call rules.list to see what’s already configured.
Create a rule — use rules.create with a natural language description. ZeroPath’s scanner will match this pattern during future scans.
Scope it — use repositoryIds to limit the rule to specific repos, globPattern to limit to specific file types, and sourceTypes to target specific entry points.
Tag it — use tagIds to associate the rule with tags for organization.
Iterate — update with rules.update as you refine the pattern.

Investigate scan results

List recent scans — call scans.list to see scan history. Filter with scanTypes: ["FullScan"] for scheduled scans or ["PrScan"] for PR scans.
Get scan details — use scans.get with a specific scanId to see status, branch, and issue counts.
Drill into findings — call issues.list with a scanId filter to see only issues from that scan.

Error Handling

Failed tool calls return structured errors:

BAD_REQUEST — Invalid input

Returned when input validation fails. Check the data.issues array for field-level details.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Input validation failed",
    "data": {
      "issues": [
        { "path": "issueIds", "message": "Required" }
      ]
    }
  }
}

UNAUTHORIZED — Invalid or missing auth

Verify your ZEROPATH_TOKEN_ID and ZEROPATH_TOKEN_SECRET are correct and the API key is active.

FORBIDDEN — Insufficient permissions

The API key does not have the required permissions for this operation. Check your key’s role in ZeroPath Settings.

NOT_FOUND — Resource doesn't exist

The specified ID (issue, scan, rule, or repository) was not found. Verify the ID is correct and belongs to your organization.

Tips

Paginate — always paginate large result sets. Use offset/limit for issues and rules, cursor/limit for scans and repositories.
Filter early — use status, severity, and repository filters to reduce response size.
Batch updates — pass multiple IDs in a single call when archiving, marking, or updating status.
Include reasons — add a reason when archiving, marking false/true positives, or changing status for audit trails.
Set org context — configure ZEROPATH_ORG_ID during installation so the server injects organizationId into every request automatically.

Getting Started

Scanning

SCA

Platform

Developer Tools

Integrations

Authentication

Issues

Scans

Repositories

Code Inspection

Rules

​Organization Scoping

​Issue Tools

​issues.list

​issues.archive

​issues.unarchive

​issues.markFalsePositive

​issues.markTruePositive

​issues.updateStatus

​issues.updateSeverity

​issues.requestInvestigation

​issues.requestBulkInvestigation

​issues.getInvestigationStatus

​Scan Tools

​scans.list

​scans.get

​Repository Tools

​repositories.list

​Code Inspection Tools

​code.search

​code.read

​code.listFiles

​Rule Tools

​rules.list

​rules.get

​rules.create

​rules.update

​rules.delete

​Common Workflows

​Error Handling

​Tips

Organization Scoping

Issue Tools

issues.list

issues.archive

issues.unarchive

issues.markFalsePositive

issues.markTruePositive

issues.updateStatus

issues.updateSeverity

issues.requestInvestigation

issues.requestBulkInvestigation

issues.getInvestigationStatus

Scan Tools

scans.list

scans.get

Repository Tools

repositories.list

Code Inspection Tools

code.search

code.read

code.listFiles

Rule Tools

rules.list

rules.get

rules.create

rules.update

rules.delete

Common Workflows

Error Handling

Tips