How to Connect Claude and ChatGPT to the Astro Docs

AI tools learn from a snapshot of the internet. That snapshot is always a little old. Astro changes often. So AI tools often write Astro code that no longer works. And they sound sure about it. The fix is simple. Give the tool the current docs to read. Docs are the official instructions. Astro makes this easy.

The Astro docs MCP server

MCP is a standard way to plug an AI tool into outside information. Astro runs an official docs server for AI tools at:

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

Once a tool is connected, it can search the docs while it works. It no longer has to rely on memory. Astro’s docs call this the best option when your tool supports it.

Claude Code

Claude Code is the Claude tool that runs in your terminal. The terminal is the typed-command window on your computer. Add the server from there. You can be 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. The same page 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 docs.

Some tools have no steps of their own. For those, use these general settings:

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

Check it’s working

Ask your tool a question whose answer changed lately. Try this one: “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 is not active.

AGENTS.md: instructions that come with your project

Make a new project with npm create astro@latest. It comes with a file called AGENTS.md. This file tells AI tools how to run the dev server. The dev server is the test copy of your site on your own computer. The file also links to the docs pages for routing, components, content and styling. Claude Code, Codex and others read it on their own.

You can add your own rules to it. These three lines 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. Use it if you want to keep Claude-only notes apart.

The dev server knows about agents

Since Astro 7, the dev server can tell when an AI coding agent is running it. An agent is an AI tool that works through tasks on its own. The dev server then 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 is why your AI tool can say “the page loads” and mean it.

EmDash does the same

EmDash projects go further. EmDash is an editing dashboard built on Astro. Its installer adds AGENTS.md. It adds a folder of skills that explain EmDash. And it adds an .mcp.json file that points at the EmDash docs. See how to build an EmDash site with AI.

Why this matters

Look at the nine mistakes AI makes with Astro. Most come from old memory. A docs connection fixes the cause, not just the symptoms.

Frequently asked questions

What is MCP?

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

Does this cost anything?

The Astro docs server is free. Using it counts towards whatever 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. For ChatGPT, they point you to OpenAI's own docs on MCP. Check there to see which plans support it.