How to Connect Claude and ChatGPT to the Astro Docs

AI tools learn from a snapshot of the internet, and the snapshot is always a little old. For Astro, which releases often, that means they confidently produce code that no longer works. The fix is to give the tool the current documentation to read. Astro makes this easy.

The Astro docs MCP server

Astro runs an official documentation server for AI tools at:

https://mcp.docs.astro.build/mcp

Once a tool is connected, it can search the docs while it works instead of relying on memory. Astro’s docs describe it as the preferred option when your tool supports it.

Claude Code

Add it from your terminal, inside your project or anywhere:

claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp

That command comes from the Astro docs, which also covers the desktop app and claude.ai.

Codex, Cursor, VS Code and others

The same Astro page has setup steps for Codex CLI, Cursor, VS Code, Windsurf, Zed, Gemini CLI, GitHub Copilot and more. For ChatGPT, Astro points to OpenAI’s own MCP documentation.

For any tool without specific steps, the generic settings are:

{
  "mcpServers": {
    "astro-docs": {
      "type": "http",
      "url": "https://mcp.docs.astro.build/mcp"
    }
  }
}

Check it’s working

Ask your tool a question whose answer changed recently, such as “where does the content collection config file go in Astro 7?” The right answer is src/content.config.ts. If it says src/content/config.ts, the connection isn’t active.

AGENTS.md: instructions that come with your project

When you create a project with npm create astro@latest, it includes a file called AGENTS.md. It tells AI tools how to run the dev server, and links to the docs pages for routing, components, content and styling. Claude Code, Codex and others read it automatically.

You can add your own rules to it. Three lines that save a lot of trouble:

## Rules for this project

- This project uses Astro 7.4. Check the docs before using any API from memory.
- Run `npm run build` after changes and fix any errors before finishing.
- Don't add packages without asking first.

Claude Code also reads a CLAUDE.md file, if you prefer to keep Claude-specific notes separate.

The dev server knows about agents

Since Astro 7, the dev server detects when an AI coding agent is running it, and runs in the background so the agent can keep working and check pages. The commands astro dev status, astro dev logs and astro dev stop manage it. On Windows, or to force it, add --background.

You don’t need to do anything for this. It’s why your AI tool can say “the page loads” and mean it.

EmDash does the same

EmDash projects go further. The installer adds AGENTS.md, a folder of skills that explain EmDash, and an .mcp.json file pointing at the EmDash docs. See how to build an EmDash site with AI.

Why this matters

Of the nine mistakes AI makes with Astro, most come from outdated memory. A docs connection fixes the cause instead of the symptoms.

Frequently asked questions

What is MCP?

Model Context Protocol, a standard way to give an AI tool access to outside information or services. Here it gives the tool the live Astro documentation.

Does this cost anything?

The Astro docs server is free. Using it counts towards whatever usage your AI tool's plan allows, the same as any other request.

Does the Astro docs server work with the free ChatGPT?

Astro's docs give setup steps for Codex and point ChatGPT users to OpenAI's own documentation on MCP. Check there for which plans support it.

Keep reading