Skip to content
Craftifact

Use MCP for AI-assisted evidence gathering

Connect your own MCP-capable AI agent to collect technical evidence snapshots for explicit package artifact and OCI subject sets, then export a review bundle from Craftifact.

Quick path

  1. Use a Pro or Team instance where evidence snapshots and the MCP interface are enabled.
  2. Create an API token or robot token with the narrow repository-family scope and read permissions your agent needs.
  3. Identify the exact package artifact IDs or OCI digests that belong to the review set.
  4. Add the Craftifact MCP endpoint to an agent or MCP client with mode=evidence_review.
  5. Ask the agent to start from craftifact_collect_evidence_snapshot and collect evidence only for the explicit subject set.
  6. Review the resulting snapshot in Craftifact and export the technical bundle through the REST endpoint when you need a portable copy.
  7. Store product-level decisions, legal conclusions, reporting status, and release acceptance in your own review system.

What the workflow does

Craftifact exposes an MCP endpoint at INSTANCE_URL/mcp. For evidence gathering, use the endpoint with mode=evidence_review. This mode is for your own AI agent; Craftifact does not run an AI model for you and does not decide compliance.

The agent helps collect a technical evidence snapshot for a bounded set of subjects. Each subject must be explicit: one package artifact ID or one OCI subject identified by repository and digest. That boundary matters because an artifact repository cannot infer your product release membership, support period, customer exposure, legal status, or release acceptance.

The resulting export is a technical evidence bundle. It can contain snapshot metadata and compact summaries for subjects, SBOM state, vulnerability state, suppressions, license and policy-decision context, and provenance values available to Craftifact. Those values are frozen at capture time, so the snapshot can still be read and exported from captured data if the original package artifact or OCI subject later disappears, is untagged, or is otherwise unavailable. It is not a compliance package and does not replace product risk assessment, vulnerability disclosure ownership, statutory reporting, update delivery, CE marking, or final release approval.

MCP mode and prompt

Use the mode query parameter:

evidence_review MCP endpoint 
https://packages.example.com/mcp?mode=evidence_review

Start from the MCP prompt:

Evidence prompt name 
craftifact_collect_evidence_snapshot

Give the prompt an explicit subject set. For package artifacts, provide artifact_id values. For OCI content, provide the repository and digest. Do not ask the agent to collect evidence for an entire repository unless you have first converted the release scope into explicit package artifact or OCI subject entries.

Export paths

Craftifact supports two export paths for technical evidence bundles, but they serve different workflows:

  • REST export for existing snapshots: GET /api/evidence/snapshots/{snapshot_id}/export/
  • UI capture for the current selected UI subject: POST /ui/api/evidence/snapshots/export/

Use the REST endpoint when automation or MCP already has a snapshot_id from the evidence snapshot workflow. This is the export path for multi-subject snapshots. The export is based on captured values, not live recomputation, so it remains useful when the source artifact or OCI subject is no longer reachable; current repository visibility still controls who can read or export the snapshot.

Use the UI action when a reviewer is working in Browse or Dependencies and wants a fresh snapshot for the currently selected package artifact or OCI subject. The UI action creates a new single-subject snapshot and opens it in the Evidence view, where the reviewer can download the bundle; it does not export an existing snapshot by ID directly.

Privileged suppression fields are not included by default. The API and UI can opt in to suppression created_by, justification, scope_key, and scope_label; doing so requires findings:suppress on every selected repository and makes the included values visible to later users who can read or download the snapshot.

Use downloaded bundles when an external release archive, audit-support workflow, or reviewer needs a portable copy of the snapshot.

Token requirements

Use a narrow API token or robot token. The token must cover every repository family referenced by the subject set. For least privilege, grant package artifact read access, composition read access for SBOM data, findings read access, license-policy read access, and pull-gate inspect access for every referenced repository. Existing findings-suppress or license-policy configure permissions also satisfy the corresponding visibility checks, but they are not needed for read-only evidence collection.

Avoid broad organization-wide tokens for one release review. If the evidence task is tied to one incident or release candidate, keep the token scoped to that set and rotate it after the session.

Set up a remote MCP client

Any agent or MCP client that supports remote MCP over HTTP with configurable headers can use the Craftifact endpoint. Pass the access token through an environment variable or secret store, not through committed files.

Example: Codex

Add the MCP server to your Codex config:

~/.codex/config.toml 
[mcp_servers.craftifact-evidence-review]
url = "https://packages.example.com/mcp?mode=evidence_review"
bearer_token_env_var = "CRAFTIFACT_MCP_TOKEN"

Replace INSTANCE_HOST with the domain where your Craftifact instance is reachable. Then start Codex from the source checkout or release workspace that contains the context you want the agent to compare against:

Codex first run (Bash) 
read -rsp "Craftifact MCP token: " CRAFTIFACT_MCP_TOKEN
printf "\n"
export CRAFTIFACT_MCP_TOKEN
codex --no-alt-screen -s workspace-write -a on-request

For the first run, prefer interactive Codex so you can approve MCP reads and confirm the subject set before the agent collects a snapshot.

Give the agent a bounded task:

Evidence collection prompt 
Use the Craftifact evidence review MCP in evidence_review mode.
Start from the prompt craftifact_collect_evidence_snapshot.
Scope the work to these package artifact IDs and OCI subjects only: SUBJECT_SET.
Collect one technical evidence snapshot for exactly that set.
Report the snapshot ID, every included subject, SBOM coverage, vulnerability and freshness state, active suppressions, license and policy-decision summaries, provenance notes, and any missing or stale inputs.
If an export bundle is needed for the created snapshot, use the REST export endpoint for the snapshot ID: GET /api/evidence/snapshots/{snapshot_id}/export/.
For a fresh single-subject snapshot from the current `Browse` or `Dependencies` selection, use the Craftifact UI capture action.
Download the bundle from the Evidence view afterward.
Do not broaden the subject set, infer release completeness, or make legal, conformity, reporting, CE marking, or release-acceptance conclusions.

Safe use

Treat the agent as a collector and reviewer of technical inputs. Ask it to name the snapshot ID, list every included subject, and call out limitations such as missing SBOMs, stale vulnerability data, failed processing, or inaccessible repositories.

Do not let the agent convert a repository name into a release boundary. Release membership, support windows, customer exposure, product risk decisions, legal interpretation, reporting duties, user communication, and release acceptance remain outside Craftifact.

Troubleshooting

If the agent asks for a broad repository review, restate the task with explicit package artifact IDs or OCI digests. If REST export fails, confirm that the snapshot_id exists and that the token can still access every repository captured by the snapshot. If Codex cancels MCP tool calls in a non-interactive run, start interactive Codex with -a on-request for the first run so you can approve MCP reads.