MCP tools

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.

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 for identity and permission configuration.

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

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.

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.

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

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.

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.

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

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