# AI Docs: Chainguard documentation for AI tools

URL: https://deploy-preview-4124--ornate-narwhal-088216.netlify.app/platform/mcp-servers/ai-docs.md
Last Modified: September 30, 2026

Search Chainguard documentation from an AI tool or other MCP client, or download the compiled documentation bundle

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/mcpThe 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:latestThe 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:
Task Former AI Docs tool Use now Read an image’s documentation get_image_docs The image’s page in the Chainguard Containers Directory. For how the image was built, the get_config and get_apko_config tools on cg-oci. List images list_images The list_repos tool on cg-oci, which lists the repositories your account can pull. To browse the public catalog, use the Chainguard Containers Directory. Check an image’s tags and build date check_image_freshness The list_tags tool on cg-oci for tags, and get_manifest for the build date. The registry_tags_list tool on cg-api also filters tags by update time. Map a Debian or Fedora package to Wolfi find_package_equivalent AI Docs, unchanged. For the Wolfi package’s versions, SBOM, and build configuration, use the search_packages tool on cg-apk. Find the Chainguard image that replaces an upstream image None The find_image_equivalent tool in AI Docs. 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-baseWhich 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.pyThe 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 8080The 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-httpPoint your MCP client at http://localhost:8080/mcp.
CLI flags Flag Env var Default Description --transport MCP_TRANSPORT stdio Transport mode: stdio or http --host MCP_HOST 0.0.0.0 HTTP server bind address --port MCP_PORT 8080 HTTP server port 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 /outputThe 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:
Download or extract the bundle. Add the file to your AI tool’s project knowledge, or attach it to a conversation. 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 Confirm that the configuration file path is correct for your platform. Restart Claude Desktop after editing the file. Check Claude Desktop’s logs for parse or connection errors. 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-mcpThe 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