---
component: provenance-governor
version: "1.7"
slug: provenance-governor/api-mcp-tools
canonical_url: "https://docs.gradle.com/develocity/provenance-governor/1.7/api-mcp-tools/"
title: "MCP tools"
description: "Reference for the MCP tool exposed by Develocity Provenance Governor for AI agent integration."
keywords:
  - "attestation"
  - "supply chain"
  - "API"
status: current
---

<!-- llms-index: https://docs.gradle.com/develocity/llms.txt -->

# MCP tools

<a id="preamble"></a>

Develocity Provenance Governor exposes an MCP (Model Context Protocol) server that enables AI agents to query Policy Scan™ data and inspect the supply chain posture of packages without parsing raw attestation JSON.

The server exposes a single tool, `inspect-package-supply-chain`, that uses progressive disclosure to control depth. Rather than separate tools for each data domain, the `include` parameter lets agents request exactly the sections they need in each call. Responses are narrative text with embedded identifiers, not JSON.

<a id="authentication"></a>

## Authentication

MCP tools are served over HTTP and use the same authentication as all Develocity Provenance Governor resources:

*   **OIDC**: HTTP Bearer auth with OIDC access tokens
    
*   **Basic**: HTTP Basic auth with configured identities
    

MCP tools do not initiate the OAuth 2.0 client credentials flow or any other token acquisition; callers must obtain and refresh access tokens externally and present them using the mechanisms above. See [Access Control](https://docs.gradle.com/develocity/provenance-governor/1.7/app-config-access-control/) for identity and permission configuration.

<a id="presigned-view-urls"></a>

## Presigned view URLs

Each tool response may include presigned URIs that deep-link to the Develocity Provenance Governor dashboard. View URLs appear on their own line in the narrative, never buried in prose. When [presigned access](https://docs.gradle.com/develocity/provenance-governor/1.7/app-config-presigned-access/) is not configured, view URLs are omitted from the response.

Section-specific view URLs include tab parameters:

*   Package overview: `https://provenance-governor.example.com/packages/{purl}`
    
*   Provenance tab: `https://provenance-governor.example.com/packages/{purl}?tab=provenance`
    
*   Dependencies tab: `https://provenance-governor.example.com/packages/{purl}?tab=dependencies`
    

<a id="inspect-package-supply-chain"></a>

## inspect-package-supply-chain

Inspects the supply chain of a package identified by its PURL. Returns narrative text describing the package’s identity, gate topology, provenance governance evaluations, and dependency compliance data.

Supported package types: `pkg:maven` (for example, `pkg:maven/org.springframework/spring-webmvc@6.2.0`) and `pkg:oci` (for example, `pkg:oci/nginx?tag=1.27`). Use `oci` not `docker` for container images.

<a id="inspect-tool-parameters"></a>

### Parameters

   
| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| packageUrl | string | yes | Package URL (PURL) to inspect. Supported types: pkg:maven and pkg:oci. |
| releaseLine | string | no | Release line label (for example, 1.x). Ignored when the PURL contains a version. |
| gate | string | no | Gate URI from the topology. Required when requesting provenanceGovernance or dependencyCompliance sections. Use include=gateTopology to discover available gate URIs. |
| include | string | no | Comma-separated dot-notation section paths controlling progressive disclosure. Omit for discovery mode. |

<a id="include-parameter-hierarchy"></a>

### The `include` parameter

The `include` parameter uses a dot-notation tree. Requesting a child path automatically includes all parent paths (for example, requesting `provenanceGovernance.evaluations` also includes `provenanceGovernance`).

 
| Path | Description |
| --- | --- |
| (empty) | Discovery mode. Returns package identity and hints for drilling deeper. |
| gateTopology | Gate URIs and labels. |
| provenanceGovernance | Governance summary for a gate. |
| provenanceGovernance.evaluations | All policy evaluations. |
| provenanceGovernance.evaluations.spec | Policy specification for each evaluation. |
| provenanceGovernance.evaluations.details | Evaluation details prose for each evaluation. |
| provenanceGovernance.evaluations.attestation | Attestation disclosure. |
| dependencyCompliance | Breakdown only: score, tier, counts by category and severity. |
| dependencyCompliance.vulnerabilities | All vulnerabilities. |
| dependencyCompliance.vulnerabilities.severity:X | Vulnerabilities filtered by severity (CRITICAL, HIGH, MODERATE, LOW). |
| dependencyCompliance.vulnerabilities.cvss | CVSS scoring details per vulnerability. |
| dependencyCompliance.vulnerabilities.advisory | OSV advisory detail for all vulnerabilities. |
| dependencyCompliance.vulnerabilities.advisory:ID | Advisory detail for specific vulnerability IDs. Multiple IDs accumulate as separate segments (for example, advisory:GHSA-xxxx,advisory:GHSA-yyyy). |
| dependencyCompliance.upgrades | All available upgrades. |
| dependencyCompliance.upgrades.strategy:X | Upgrades filtered by strategy (MAJOR, MINOR, PATCH). |
| dependencyCompliance.scoreBreakdown | Score breakdown by category (vulnerability, upgrade, weights, next tier). |
| dependencyCompliance.remediations | Remediation actions from Policy Scan data. |

Parameterized filter paths are supported on evaluations and dependency compliance sections. For example: `provenanceGovernance.evaluations.status:UNSATISFIED.kind:BuildTool`

<a id="intent-driven-narration"></a>

### Intent-driven narration

The tool adapts its response based on the PURL:

*   **Unversioned PURL** (for example, `pkg:maven/com.google.guava/guava`): The response includes discovery content such as known versions and release lines.
    
*   **Versioned PURL** (for example, `pkg:maven/com.google.guava/guava@33.4.0-jre`): Discovery content is skipped. The response focuses on the specific version’s supply chain posture.
    

<a id="narrative-response-format"></a>

### Response format

Responses are narrative text, not JSON. Each response ends with one or more `->` hint lines containing literal parameter values for the next logical invocation. The agent can copy-paste these hints without interpolation.

Identifiers such as PURLs, CVE IDs, and gate URIs appear as unambiguous, copy-pasteable tokens in the narrative.

All lists are bounded. When a section contains more items than the bound, the narration includes a count of remaining items and a dashboard view URL for the full data.

<a id="mcp-error-handling"></a>

### Error handling

Errors that the agent can act on (for example, malformed PURL, unsupported package type, unknown gate URI) are returned as narrated text in a normal response. The narration explains what went wrong and provides the information the agent needs to correct its inputs and retry. The MCP response `isError` flag is `false` for these cases.

Errors that the agent cannot resolve (for example, an internal service failure) propagate as exceptions. The MCP framework sets `isError: true` on the response. Retrying with different parameters will not help; the agent should report the failure to the user.

The following actionable error conditions are narrated:

*   **Malformed PURL**: Explains the expected format with examples of both supported types
    
*   **Unsupported package type**: Lists the supported types (`maven`, `oci`)
    
*   **Unknown include path**: Lists all valid paths
    
*   **Package not found**: Confirms the PURL was valid but no data exists
    
*   **Unknown gate URI**: Lists the available gate URIs from the topology
    
*   **No gates configured**: Explains that gates appear after a Policy Scan definition evaluates an attestation
    

<a id="agent-workflow-example"></a>

## Worked example: AI agent workflow

A typical agent session uses progressive disclosure to drill from discovery to detail:

1.  **Discovery**. The agent calls `inspect-package-supply-chain` with `packageUrl=pkg:maven/com.google.guava/guava@33.4.0-jre` and no `include`. The response confirms the package is tracked and provides hints for deeper inspection.
    
    ```
    Package: com.google.guava/guava 33.4.0-jre (Maven)
    
    This package is tracked by Develocity Provenance Governor.
    Policy Scan data is available.
    
    -> To discover gate topology use: inspect-package-supply-chain
       with packageUrl=pkg:maven/com.google.guava/guava@33.4.0-jre,
       include=gateTopology
    ```
    
2.  **Gate topology**. The agent adds `include=gateTopology`. The response lists available gates with their URIs, and hints guide the agent to select a gate for deeper inspection.
    
    ```
    Package: com.google.guava/guava 33.4.0-jre (Maven)
    
    Gates (2):
      1. Production Release (uri: /api/gates/production-release)
      2. Internal Preview (uri: /api/gates/internal-preview)
    
    -> To inspect provenance governance use: inspect-package-supply-chain
       with packageUrl=pkg:maven/com.google.guava/guava@33.4.0-jre,
       include=provenanceGovernance,
       gate=/api/gates/production-release
    -> To inspect dependency compliance use: inspect-package-supply-chain
       with packageUrl=pkg:maven/com.google.guava/guava@33.4.0-jre,
       include=dependencyCompliance,
       gate=/api/gates/production-release
    ```
    
3.  **Provenance governance**. The agent selects a gate and requests evaluations with spec and details. The response shows which Policy Scan evaluations passed and which require attention.
    
    ```
    Package: com.google.guava/guava 33.4.0-jre (Maven)
    Gate: Production Release
    
    Provenance Governance: 5 of 6 evaluations satisfied
    
      1. Build Tool [SATISFIED]: Gradle 8.12 detected
         Spec: buildTool must be Gradle >= 8.0 or Maven >= 3.9
         ...
    
      View full provenance governance:
      https://provenance-governor.example.com/packages/pkg:maven/
      com.google.guava/guava@33.4.0-jre?tab=provenance
    
    -> To inspect dependency compliance use: inspect-package-supply-chain
       with packageUrl=pkg:maven/com.google.guava/guava@33.4.0-jre,
       include=dependencyCompliance,
       gate=/api/gates/production-release
    ```
    
4.  **Dependency compliance**. The agent drills into vulnerabilities. The response lists vulnerabilities bounded to 20, with overflow to the dashboard.
    
    ```
    Package: com.google.guava/guava 33.4.0-jre (Maven)
    Gate: Production Release
    
    Dependency Compliance: 4 vulnerabilities across 2 dependencies
    
      1. CVE-2024-1234 (HIGH, CVSS 8.1), protobuf-java 3.25.0
      2. CVE-2024-5678 (MEDIUM, CVSS 5.3), protobuf-java 3.25.0
      3. CVE-2024-9012 (LOW, CVSS 2.1), error-prone-annotations 2.27.0
      4. CVE-2024-3456 (LOW, CVSS 1.8), error-prone-annotations 2.27.0
    
      View full dependency compliance:
      https://provenance-governor.example.com/packages/pkg:maven/
      com.google.guava/guava@33.4.0-jre?tab=dependencies
    
    -> To see CVSS details use: inspect-package-supply-chain
       with packageUrl=pkg:maven/com.google.guava/guava@33.4.0-jre,
       include=dependencyCompliance.vulnerabilities.cvss,
       gate=/api/gates/production-release
    ```