AI Docs: Chainguard documentation for AI tools

AI Docs gives AI tools access to Chainguard’s documentation: the guides, security references, and tool references published on this site, plus the package and image mappings that the Dockerfile Converter (dfc) uses. You can connect to it as an MCP server, which returns only the sections that match each query, or download the whole documentation bundle and give it to an AI tool directly.

AI Docs has no live container image data. It can tell you which Chainguard image replaces an upstream image, but for an image’s tags, SBOM, or build date, use the cg-oci MCP server. Refer to Container image data.

For background on MCP and the other Chainguard MCP servers, refer to the MCP servers overview.

Why use the MCP server?

• Lower context cost. Clients fetch only the sections they need instead of loading the entire multi-megabyte bundle into every prompt.
• Structured queries. Search for a guide, read the security documentation, or find a package or image equivalent without writing custom scrapers.
• IDE integration. Works with Claude Code, Claude Desktop, Cursor, and other MCP-compatible clients, so engineers can reference Chainguard docs while they write code.

Connect to the server

Prerequisites

• An MCP-compatible client such as Claude Code, Claude Desktop, or Cursor

Hosted server (recommended)

Chainguard hosts a public MCP server at https://mcp.edu.chainguard.dev/mcp. This is the fastest way to get started — no Docker or local setup required, and no sign-in.

How you register the server depends on your MCP client. Clients that support HTTP transport natively can connect to the URL directly. Clients that only spawn local processes (including Claude Desktop) need a small bridge such as mcp-remote.

Claude Code

Run this command:

claude mcp add --transport http chainguard-docs https://mcp.edu.chainguard.dev/mcp

The server is available immediately. Verify it with claude mcp list.

By default, the command registers the server for the current directory only. To make it available in every directory, add --scope user.

Claude Desktop

Claude Desktop reads MCP servers from a JSON file but does not yet support HTTP transport directly. Use mcp-remote to bridge to the hosted server:

{
  "mcpServers": {
    "chainguard-docs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.edu.chainguard.dev/mcp"
      ]
    }
  }
}

The configuration file lives at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

npx downloads and runs mcp-remote on demand, so you need Node.js installed on the host. Restart Claude Desktop after saving the file.

Cursor and other clients with native HTTP transport

Add the server URL to your client’s MCP configuration:

{
  "mcpServers": {
    "chainguard-docs": {
      "url": "https://mcp.edu.chainguard.dev/mcp"
    }
  }
}

Consult your client’s documentation for the configuration file location, then restart the client. The Chainguard documentation tools appear in the next conversation.

Local Docker setup

To run the MCP server locally, pull the container image:

docker pull ghcr.io/chainguard-dev/ai-docs:latest

The image’s serve-mcp entrypoint uses the stdio transport, which works with any MCP client that launches local processes. For Claude Desktop, add this block to claude_desktop_config.json:

{
  "mcpServers": {
    "chainguard-docs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "ghcr.io/chainguard-dev/ai-docs:latest",
        "serve-mcp"
      ]
    }
  }
}

Restart the client after saving the file.

Available tools

The server exposes five tools for searching documentation and mapping packages and images.

search_docs

Search across all Chainguard documentation for relevant content.

Parameters:

• query (string, required): Search query
• max_results (integer, optional): Maximum results to return (default: 5)

Example prompts:

• “Search Chainguard docs for python CVE management”
• “Find information about FIPS compliance”
• “Search for nginx configuration examples”

get_security_docs

Get security-related documentation including CVE management, SBOMs, and signing.

Example prompts:

• “How does Chainguard handle CVEs?”
• “Show me security documentation”
• “Explain SBOM generation”

get_tool_docs

Get documentation for Chainguard tools and ecosystem components.

Parameters:

• tool_name (string, required): Tool name: wolfi, apko, melange, or chainctl

Example prompts:

• “Show me wolfi documentation”
• “How do I use apko?”
• “Explain melange”

find_package_equivalent

Find the Wolfi package that replaces a Debian, Fedora, or Alpine package. Use this when migrating a Dockerfile to a Chainguard image and translating package names for apk add.

Parameters:

• package (string, required): Upstream OS package name (for example, “build-essential”, “libssl-dev”, “python3-pip”)
• distro (string, optional): Source distribution to search: debian, fedora, or alpine. Searches all distributions if omitted. The catalog has no Alpine mappings yet, so an Alpine lookup returns no match.

Example prompts:

• “What’s the Wolfi equivalent of Debian’s build-essential?”
• “Find the Chainguard package for libssl-dev”
• “I need to replace python3-pip in my Dockerfile”

find_image_equivalent

Find the Chainguard image that replaces an upstream container image, using the Dockerfile Converter mappings. Use this when migrating a Dockerfile’s FROM line. The tool matches names the way the Dockerfile Converter does: it ignores tags and digests, accepts Docker Hub names with or without a docker.io/ host, and falls back to the last part of the name. It returns the Chainguard image name and a pull reference.

Parameters:

• image (string, required): Upstream image reference as it appears in a FROM line (for example, “bitnami/pgpool”, “docker.io/library/node:20”, “gcr.io/kaniko-project/executor”)

Example prompts:

• “What Chainguard image replaces bitnami/pgpool?”
• “I’m migrating a Dockerfile that starts with FROM quay.io/prometheus/snmp-exporter. What’s the Chainguard equivalent?”

Container image data

AI Docs doesn’t carry live container image data. Chainguard’s product MCP servers read it from the registry and package index at the moment you ask, so their answers describe the images as they are now. These servers require a Chainguard account. For connection and authentication steps, refer to the MCP servers overview.

This table shows where to go for each image task, and which AI Docs tool used to cover it:

Note: AI Docs removed its three image tools at the end of September 2026. Their data came from a snapshot of image documentation that had stopped updating.

The AI Docs server also sends these pointers to each client when it connects, so an AI tool asked about an image can direct you to the right server.

Image references

Write a Chainguard image reference as cgr.dev/<your-organization>/<image>, replacing <your-organization> with your Chainguard organization’s name. Most Chainguard images are available only to organizations entitled to them, in the organization’s own namespace. The public cgr.dev/chainguard namespace serves a free subset with latest-style tags only, so an image reference that works for one organization may not work in cgr.dev/chainguard. To check which images your organization can pull, use the list_repos tool on cg-oci.

Package catalog

The find_package_equivalent and find_image_equivalent tools draw from a package catalog that ships with the server. The catalog holds the Dockerfile Converter’s mappings: Debian and Fedora packages to their Wolfi equivalents, with no Alpine mappings, and upstream images to the Chainguard images that replace them. Each documentation build regenerates it.

The catalog file is package-mappings.json. The container image and the extracted files also include an identical copy named image-catalog.json, the file’s earlier name, so configurations that point at that name continue to work.

Example usage

Sample exchanges from a Claude Code session with chainguard-docs connected. The documentation changes often, so your answers will differ.

How do I use a multi-stage build with the Chainguard Python image?

  Called chainguard-docs (ctrl+o to expand)

● Use the -dev variant as the build stage and the minimal image as the
  runtime stage. The -dev image includes pip and a shell, so install your
  dependencies there, then copy them into the minimal image, which has
  only Python and its standard library. The Getting started with the
  Python Chainguard Container guide walks through a full example.

What's the Wolfi equivalent of Debian's build-essential?

  Called chainguard-docs (ctrl+o to expand)

● Debian's build-essential maps to build-base in Wolfi. Install it with:

  apk add build-base

Which Chainguard image replaces bitnami/pgpool?

  Called chainguard-docs (ctrl+o to expand)

● bitnami/pgpool maps to Chainguard's pgpool2 image. Pull it as
  cgr.dev/<your-organization>/pgpool2, replacing <your-organization>
  with your Chainguard organization's name.

Standalone installation (without Docker)

The server script and its dependencies live in the edu repository. The documentation files ship inside the container image, which you can extract once and reuse.

# Download the MCP server script and requirements
curl -LO https://raw.githubusercontent.com/chainguard-dev/edu/main/scripts/mcp-server.py
curl -LO https://raw.githubusercontent.com/chainguard-dev/edu/main/scripts/mcp-requirements.txt

# Extract the documentation bundle from the container image
docker run --rm --user "$(id -u):$(id -g)" \
  -v $(pwd):/output ghcr.io/chainguard-dev/ai-docs:latest extract /output
# Writes chainguard-ai-docs.md, package-mappings.json, image-catalog.json,
# checksums.txt, and verification.sh into a chainguard-ai-docs/ subdirectory

# Install dependencies into a virtual environment
python3 -m venv .venv
.venv/bin/pip install -r mcp-requirements.txt

# Run the server
DOCS_PATH=chainguard-ai-docs/chainguard-ai-docs.md \
CATALOG_PATH=chainguard-ai-docs/package-mappings.json \
.venv/bin/python mcp-server.py

The container runs as a non-root user, so pass --user to let it write to the mounted directory and to leave the extracted files owned by you.

To run this script under Claude Desktop, point the configuration at the local files:

{
  "mcpServers": {
    "chainguard-docs": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/mcp-server.py"],
      "env": {
        "DOCS_PATH": "/path/to/chainguard-ai-docs.md",
        "CATALOG_PATH": "/path/to/package-mappings.json"
      }
    }
  }
}

Self-host with HTTP transport

Run your own HTTP instance when you need to expose the server inside a firewall or with custom configuration.

From the standalone script

.venv/bin/python mcp-server.py --transport http --port 8080

The server binds to http://0.0.0.0:8080 with the MCP endpoint at /mcp.

Environment variables work too:

MCP_TRANSPORT=http MCP_PORT=8080 .venv/bin/python mcp-server.py

From Docker

docker run --rm -p 8080:8080 ghcr.io/chainguard-dev/ai-docs:latest serve-mcp-http

Point your MCP client at http://localhost:8080/mcp.

CLI flags

Use the documentation without a server

The documentation bundle is one Markdown file holding every page on this site, plus the Dockerfile Converter mappings. It carries its compilation date at the top of the file.

Download the bundle

Download the bundle directly. It refreshes nightly.

curl -LO https://edu.chainguard.dev/downloads/chainguard-complete-docs.md

Extract the bundle from the container image

The container image carries the same bundle, with checksums and a verification script, and rebuilds whenever the documentation changes. Run the image with no command to print its available commands. To verify the bundle and extract it:

docker pull ghcr.io/chainguard-dev/ai-docs:latest

docker run --rm ghcr.io/chainguard-dev/ai-docs:latest verify

docker run --rm --user "$(id -u):$(id -g)" \
  -v $(pwd):/output ghcr.io/chainguard-dev/ai-docs:latest extract /output

The extracted bundle is chainguard-ai-docs/chainguard-ai-docs.md.

To verify the container image’s signature before you use it:

cosign verify ghcr.io/chainguard-dev/ai-docs:latest \
  --certificate-identity-regexp ".*github.com/chainguard-dev/edu.*" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

Give the bundle to an AI tool

The bundle is larger than most AI tools can hold in a single conversation. Tools that index attached files, such as a project knowledge base, handle it better than a chat that reads the whole file at once. For most questions, the MCP server is the better fit, because it returns only the sections that match.

To use the bundle:

1. Download or extract the bundle.
2. Add the file to your AI tool’s project knowledge, or attach it to a conversation.
3. Ask your question. The AI tool answers from Chainguard’s documentation rather than from its training data alone.

Security features

The container image follows the standard Chainguard pattern:

• Built on cgr.dev/chainguard/wolfi-base
• Runs as a non-root user
• Signed with Cosign
• Rebuilt whenever the documentation changes, so known CVEs don’t accumulate

Each build also scans the bundle for credential patterns before publishing it. For the compilation process and verification steps, refer to AI documentation security. The build logs and the compilation scripts are public.

Troubleshooting

Server does not appear in Claude Desktop

1. Confirm that the configuration file path is correct for your platform.
2. Restart Claude Desktop after editing the file.
3. Check Claude Desktop’s logs for parse or connection errors.
4. For the local Docker block, confirm Docker is running.

Connection issues

Test the hosted server with curl:

curl -X POST https://mcp.edu.chainguard.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

A JSON response listing the server’s capabilities confirms the connection.

To test a local Docker server:

docker run --rm -i ghcr.io/chainguard-dev/ai-docs:latest serve-mcp

The container prints startup messages and then waits for stdio input.

An AI tool can’t find image details

AI Docs has no live container image data. Connect cg-oci for live registry data, or look up the image in the Chainguard Containers Directory. Refer to Container image data.

Documentation out of date

The hosted server updates automatically. For the local Docker setup, pull a fresh image:

docker pull ghcr.io/chainguard-dev/ai-docs:latest

Resources

• Chainguard MCP servers overview
• cg-oci: the Chainguard container registry MCP server
• Model Context Protocol documentation
• Chainguard MCP blog post
• AI documentation security
• Chainguard Containers Directory

Need help?

• Get support
• Community Slack
• GitHub Issues