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

# MCP Tools Reference

> Complete reference for all tools available through the ZeroPath MCP Server

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.

<CardGroup cols={2}>
  <Card title="Issues" icon="shield-exclamation">
    10 tools — list, triage, investigate, update status and severity
  </Card>

  <Card title="Scans" icon="magnifying-glass">
    3 tools — list scan history, get scan details, rescan PRs
  </Card>

  <Card title="Repositories" icon="code-branch">
    1 tool — list repositories with filtering
  </Card>

  <Card title="Code Inspection" icon="file-code">
    3 tools — search, read, and list files in connected repositories
  </Card>

  <Card title="Rules" icon="gavel">
    5 tools — full CRUD for custom security rules
  </Card>
</CardGroup>

## 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.

<Tip>
  Set `ZEROPATH_ORG_ID` during [installation](/mcp/installation) to avoid passing `organizationId` in every call.
</Tip>

***

## 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`)                                                                                                                                                |
| `vulnerabilityClassFilters` | object\[] | No       | Structured filter: each object has `operator` (`equals`, `contains`, or `startsWith`) and `value` (string). Use for partial or prefix class matching; `vulnerabilityClasses` is a plain string list. |
| `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                                                                                                                                                      |

<CodeGroup>
  ```json Request theme={null}
  {
    "offset": 0,
    "limit": 25,
    "statuses": ["PENDING_REVIEW"],
    "scoreLevels": ["CRITICAL", "HIGH"],
    "sortBy": "score",
    "sortOrder": "desc"
  }
  ```

  ```json Response theme={null}
  {
    "issues": [
      {
        "id": "issue_abc123",
        "title": "SQL Injection in user lookup",
        "score": 9.2,
        "status": "PENDING_REVIEW",
        "repository": { "id": "repo_123", "name": "backend-api" },
        "vulnerabilityClass": "SQL Injection",
        "createdAt": "2025-10-16T12:34:56Z"
      }
    ],
    "counts": {
      "total": 42,
      "byStatus": { "PENDING_REVIEW": 12, "REVIEWING": 8 }
    },
    "effectiveFilters": { "statuses": ["PENDING_REVIEW"] }
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123", "issue_456"],
    "reason": "Confirmed duplicate"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123"]
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_789"],
    "reason": "Input is sanitized by middleware"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_101", "issue_102"]
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

### 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                   |

<Warning>
  The field name is `issueStatus`, not `status`. Using the wrong field name will cause a validation error.
</Warning>

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123"],
    "issueStatus": "RESOLVED",
    "reason": "Fixed in PR #456"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true,
    "updatedCount": 1
  }
  ```
</CodeGroup>

### 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 |

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

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123",
    "severity": 8.5,
    "reason": "Upgraded after confirming public exposure"
  }
  ```

  ```json Response theme={null}
  {
    "ok": true
  }
  ```
</CodeGroup>

<h3 id="mcp-issues-request-investigation">
  issues.requestInvestigation
</h3>

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

<Note>
  **REST vs MCP:** The public HTTP API exposes a single procedure, `POST /api/v2/issues/requestInvestigation`, with an `issueIds` array (one or more IDs). That route uses the same backend path as the **issues.requestBulkInvestigation** MCP tool. This **issues.requestInvestigation** MCP tool calls the **single-issue** tRPC mutation instead — there is no matching `POST …/{id}/investigate` REST endpoint.
</Note>

| Parameter        | Type   | Required | Description                                                                                                                                                                                 |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issueId`        | string | Yes      | Issue ID to investigate                                                                                                                                                                     |
| `context`        | string | No       | Additional context to guide the investigation (max 20,000 characters). You can include details such as how the affected code is used, deployment context, or specific concerns to focus on. |
| `organizationId` | string | No       | Injected from `ZEROPATH_ORG_ID` when configured                                                                                                                                             |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123",
    "context": "This endpoint is exposed to unauthenticated users and handles file uploads. Please check whether the path traversal is reachable from the public route."
  }
  ```

  ```json Response theme={null}
  {
    "investigationId": "inv_abc123",
    "status": "created"
  }
  ```
</CodeGroup>

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.

<h3 id="mcp-issues-request-bulk-investigation">
  issues.requestBulkInvestigation
</h3>

Request investigations for multiple issues at once.

<Note>
  **REST mapping:** `POST /api/v2/issues/requestInvestigation` with `{ issueIds, context?, organizationId? }`. This is the HTTP surface for bulk investigations; it is **not** the same MCP tool name as **issues.requestInvestigation** ([single-issue tRPC tool](#mcp-issues-request-investigation) above).
</Note>

| Parameter        | Type      | Required | Description                                                                                                                                                                                      |
| ---------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issueIds`       | string\[] | Yes      | Issue IDs to investigate                                                                                                                                                                         |
| `context`        | string    | No       | Additional context to guide all investigations in this batch (max 20,000 characters). You can include details such as deployment context or specific concerns that apply to the group of issues. |
| `organizationId` | string    | No       | Injected from `ZEROPATH_ORG_ID` when configured                                                                                                                                                  |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueIds": ["issue_123", "issue_456", "issue_789"],
    "context": "These issues were found in our payment processing service which is PCI-scoped. Please prioritize exploitability assessment."
  }
  ```

  ```json Response theme={null}
  {
    "created": 2,
    "skipped": 1,
    "unauthorized": 0
  }
  ```
</CodeGroup>

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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "issueId": "issue_123"
  }
  ```

  ```json Response theme={null}
  {
    "id": "inv_abc123",
    "status": "COMPLETED",
    "startedAt": "2026-03-15T10:00:00Z",
    "completedAt": "2026-03-15T10:02:30Z",
    "resultValidated": "CONFIRMED",
    "resultSecurityAssessment": "The SQL injection is exploitable via the search parameter...",
    "error": null,
    "createdAt": "2026-03-15T09:59:00Z"
  }
  ```
</CodeGroup>

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                       |

<CodeGroup>
  ```json Request (first page) theme={null}
  {
    "limit": 10,
    "repositoryIds": ["repo_123"],
    "scanTypes": ["FullScan"]
  }
  ```

  ```json Request (next page) theme={null}
  {
    "cursor": {
      "createdAt": "2025-10-15T08:00:00Z",
      "id": "scan_xyz"
    },
    "limit": 10
  }
  ```

  ```json Response theme={null}
  {
    "scans": [
      {
        "scanId": "scan_abc123",
        "repositoryId": "repo_123",
        "repositoryName": "backend-api",
        "status": "Finished",
        "codeScanType": "FullScan",
        "createdAt": "2025-10-16T12:00:00Z",
        "scanFinishedAt": "2025-10-16T12:08:00Z",
        "issueCounts": {
          "PENDING_REVIEW": 3,
          "RESOLVED": 12,
          "newOpen": 2
        }
      }
    ],
    "nextCursor": { "createdAt": "2025-10-15T08:00:00Z", "id": "scan_xyz" },
    "hasMore": true,
    "isFirstPage": true
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "scanId": "scan_abc123"
  }
  ```

  ```json Response theme={null}
  {
    "scanId": "scan_abc123",
    "repositoryId": "repo_123",
    "repositoryName": "backend-api",
    "status": "Finished",
    "codeScanType": "FullScan",
    "scanTargetBranch": "main",
    "finished": true,
    "createdAt": "2025-10-16T12:00:00Z",
    "scanFinishedAt": "2025-10-16T12:08:00Z",
    "issueCounts": {
      "PENDING_REVIEW": 3,
      "REVIEWING": 1,
      "RESOLVED": 12,
      "newOpen": 2,
      "open": 5
    },
    "scanType": "code"
  }
  ```
</CodeGroup>

### scans.rescanPR

Trigger a rescan of a pull request or merge request. Pass the ID of a previous PR scan and the platform will re-fetch the pull request and create new scan(s). Supports GitHub PRs and GitLab MRs.

| Parameter        | Type    | Required | Description                                                                                              |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `scanId`         | string  | Yes      | ID of a previous PR scan to rescan                                                                       |
| `force`          | boolean | No       | When true, bypasses duplicate detection and rescans even if a scan for the current commit already exists |
| `organizationId` | string  | No       | Injected from `ZEROPATH_ORG_ID` when configured                                                          |

<CodeGroup>
  ```json Request theme={null}
  {
    "scanId": "scan_abc123",
    "force": false
  }
  ```

  ```json Response theme={null}
  {
    "outcome": "scans_created",
    "message": "Created 1 new scan(s)",
    "scanCount": 1
  }
  ```
</CodeGroup>

The `outcome` field indicates what happened:

| Outcome               | Meaning                                                                      |
| --------------------- | ---------------------------------------------------------------------------- |
| `scans_created`       | New scan(s) were created successfully                                        |
| `skipped_duplicate`   | A scan for the current commit already exists (use `force: true` to override) |
| `skipped_not_enabled` | PR scanning is not enabled for this repository                               |
| `skipped_no_targets`  | No valid scan targets found for the pull request                             |
| `closed`              | The pull request is closed                                                   |
| `error`               | An error occurred during rescan                                              |

***

## 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              |

<CodeGroup>
  ```json Request theme={null}
  {
    "limit": 50,
    "sortBy": "issues",
    "sortDirection": "desc",
    "getCounts": true
  }
  ```

  ```json Response theme={null}
  {
    "items": [
      {
        "id": "repo_123",
        "projectId": "proj_456",
        "name": "backend-api",
        "defaultScanTargetBranch": "main",
        "tags": [{ "id": "tag_1", "name": "production", "priority": 1 }],
        "issueCounts": {
          "newOpen": 5,
          "open": 12,
          "patched": 30,
          "archived": 2,
          "falsePositive": 3,
          "patchable": 4,
          "closed": 8,
          "silenced": 1
        },
        "vcs": {
          "vcsType": "github",
          "url": "https://github.com/acme/backend-api",
          "linkActive": true
        }
      }
    ],
    "nextCursor": "eyJuYW1lIjoiYmFja2VuZC1hcGkifQ",
    "hasMore": true,
    "totalCount": 87
  }
  ```
</CodeGroup>

***

## 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                                      |

<CodeGroup>
  ```json Request theme={null}
  {
    "repositoryId": "repo_123",
    "query": "password",
    "pathPrefix": "src/auth",
    "limit": 5
  }
  ```

  ```json Response theme={null}
  {
    "provider": "github",
    "repositoryId": "repo_123",
    "query": "password",
    "ref": null,
    "pathPrefix": "src/auth",
    "hasNextPage": true,
    "totalMatches": 12,
    "items": [
      {
        "path": "src/auth/login.ts",
        "line": 42,
        "preview": "const hashedPassword = await bcrypt.hash(password, 10);",
        "url": "https://github.com/acme/backend/blob/main/src/auth/login.ts#L42"
      }
    ]
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "repositoryId": "repo_123",
    "path": "src/auth/login.ts",
    "startLine": 40,
    "endLine": 50
  }
  ```

  ```json Response theme={null}
  {
    "provider": "github",
    "repositoryId": "repo_123",
    "path": "src/auth/login.ts",
    "ref": "main",
    "startLine": 40,
    "endLine": 50,
    "totalLines": 120,
    "content": "...",
    "byteLength": 450,
    "truncatedByLineRange": true,
    "truncatedByByteLimit": false,
    "url": "https://github.com/acme/backend/blob/main/src/auth/login.ts"
  }
  ```
</CodeGroup>

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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "repositoryId": "repo_123",
    "path": "src/auth"
  }
  ```

  ```json Response theme={null}
  {
    "provider": "github",
    "repositoryId": "repo_123",
    "ref": "main",
    "path": "src/auth",
    "hasMore": false,
    "nextCursor": null,
    "items": [
      { "path": "src/auth/login.ts", "name": "login.ts", "type": "file", "size": 2048 },
      { "path": "src/auth/middleware", "name": "middleware", "type": "dir", "size": null }
    ]
  }
  ```
</CodeGroup>

<Note>
  Code inspection is currently supported for **GitHub** and **GitLab** repositories. Bitbucket, generic Git, and uploaded repositories are not yet supported.
</Note>

***

## 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "offset": 0,
    "limit": 25
  }
  ```

  ```json Response theme={null}
  {
    "rules": [
      {
        "id": "rule_xyz789",
        "name": "Detect unsafe eval",
        "rule": "Detect any use of eval() on user input",
        "globPattern": "**/*.js",
        "sourceTypes": ["FILE_HANDLER"],
        "repositoryIds": ["repo_123"],
        "tags": [{ "id": "tag_1", "name": "critical-rules" }],
        "createdAt": "2025-09-01T00:00:00Z",
        "updatedAt": "2025-10-10T12:00:00Z"
      }
    ],
    "totalCount": 8,
    "hasMore": false,
    "nextOffset": null
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "ruleId": "rule_xyz789"
  }
  ```

  ```json Response theme={null}
  {
    "id": "rule_xyz789",
    "name": "Detect unsafe eval",
    "rule": "Detect any use of eval() on user input",
    "globPattern": "**/*.js",
    "sourceTypes": ["FILE_HANDLER"],
    "repositories": [
      { "id": "repo_123", "name": "backend-api" }
    ],
    "tags": [{ "id": "tag_1", "name": "critical-rules" }],
    "createdAt": "2025-09-01T00:00:00Z",
    "updatedAt": "2025-10-10T12:00:00Z"
  }
  ```
</CodeGroup>

### 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                                                                         |

<CodeGroup>
  ```json Request theme={null}
  {
    "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"]
  }
  ```

  ```json Response theme={null}
  {
    "id": "rule_xyz789",
    "name": "Detect unsafe eval",
    "rule": "Detect any use of eval() on user input",
    "globPattern": "**/*.{js,ts}",
    "sourceTypes": ["HTTP_HANDLER", "FILE_HANDLER"],
    "repositoryIds": ["repo_123"],
    "tags": [{ "id": "tag_1", "name": "critical-rules" }],
    "createdAt": "2025-10-16T14:00:00Z",
    "updatedAt": "2025-10-16T14:00:00Z"
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "ruleId": "rule_xyz789",
    "name": "Detect unsafe eval (updated)",
    "globPattern": "**/*.{js,ts,jsx,tsx}"
  }
  ```

  ```json Response theme={null}
  {
    "id": "rule_xyz789",
    "name": "Detect unsafe eval (updated)",
    "rule": "Detect any use of eval() on user input",
    "globPattern": "**/*.{js,ts,jsx,tsx}",
    "sourceTypes": ["HTTP_HANDLER", "FILE_HANDLER"],
    "repositoryIds": ["repo_123"],
    "tags": [{ "id": "tag_1", "name": "critical-rules" }],
    "createdAt": "2025-10-16T14:00:00Z",
    "updatedAt": "2025-10-16T15:30:00Z"
  }
  ```
</CodeGroup>

### 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 |

<CodeGroup>
  ```json Request theme={null}
  {
    "ruleId": "rule_xyz789"
  }
  ```

  ```json Response theme={null}
  {
    "success": true
  }
  ```
</CodeGroup>

***

## Common Workflows

<AccordionGroup>
  <Accordion title="Triage new issues">
    1. **List pending issues** — call `issues.list` with `statuses: ["PENDING_REVIEW"]` sorted by `score` descending.
    2. **Review each issue** — ask your AI assistant to summarize the vulnerability and affected code.
    3. **Classify** — use `issues.markTruePositive` or `issues.markFalsePositive` with a reason.
    4. **Update status** — move confirmed issues to `REVIEWING` or `PATCHING` with `issues.updateStatus`.
    5. **Adjust severity** — if the auto-assigned score doesn't match your assessment, use `issues.updateSeverity` with a value from 0 to 10.
  </Accordion>

  <Accordion title="Create custom rules">
    1. **List existing rules** — call `rules.list` to see what's already configured.
    2. **Create a rule** — use `rules.create` with a natural language description. ZeroPath's scanner will match this pattern during future scans.
    3. **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.
    4. **Tag it** — use `tagIds` to associate the rule with tags for organization.
    5. **Iterate** — update with `rules.update` as you refine the pattern.
  </Accordion>

  <Accordion title="Investigate scan results">
    1. **List recent scans** — call `scans.list` to see scan history. Filter with `scanTypes: ["FullScan"]` for scheduled scans or `["PrScan"]` for PR scans.
    2. **Get scan details** — use `scans.get` with a specific `scanId` to see status, branch, and issue counts.
    3. **Drill into findings** — call `issues.list` with a `scanId` filter to see only issues from that scan.
  </Accordion>
</AccordionGroup>

***

## Error Handling

Failed tool calls return structured errors:

<AccordionGroup>
  <Accordion title="BAD_REQUEST — Invalid input">
    Returned when input validation fails. Check the `data.issues` array for field-level details.

    ```json theme={null}
    {
      "error": {
        "code": "BAD_REQUEST",
        "message": "Input validation failed",
        "data": {
          "issues": [
            { "path": "issueIds", "message": "Required" }
          ]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="UNAUTHORIZED — Invalid or missing auth">
    Verify your `ZEROPATH_TOKEN_ID` and `ZEROPATH_TOKEN_SECRET` are correct and the API key is active.
  </Accordion>

  <Accordion title="FORBIDDEN — Insufficient permissions">
    The API key does not have the required permissions for this operation. Check your key's role in [ZeroPath Settings](https://zeropath.com/app/settings/api).
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

***

## 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](/mcp/installation) so the server injects `organizationId` into every request automatically.