Building Astro sites with AI tools

AI-powered editors and agentic coding tools generally have good knowledge of Astro’s core APIs and concepts. However, some may use older APIs and may not be aware of newer features or recent changes to the framework.

This guide covers how to enhance AI tools with up-to-date Astro knowledge and provides best practices for building Astro sites with AI assistance.

Context files

Astro provides llms.txt and llms-full.txt files that contains the full docs content in a format optimized for AI consumption. These are static files of the Astro Docs content in a streamlined Markdown format. Some AI tools can auto-discover these files if you provide https://docs.astro.build as a docs source.

While these files provide a minimal, easy-to-parse version of Astro’s documentation, they are large files that will use a lot of tokens if used directly in context and will need to be updated regularly to stay current. They are best used as a fallback when the AI tool does not have access to the latest documentation in other ways. The MCP server provides more efficient access to the full documentation with real-time search capabilities, making it the preferred option when available.

Astro Docs MCP Server

You can ensure your AI tools have current Astro knowledge through the Astro Docs MCP (Model Context Protocol) server. This provides real-time access to the latest documentation, helping AI tools avoid outdated recommendations and ensuring they understand current best practices.

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI tools to access external tools and data sources.

Unlike AI models trained on static data, the MCP server provides access to the latest Astro documentation. The server is free, open-source, and runs remotely with nothing to install locally.

The Astro Docs MCP server uses the kapa.ai API to maintain an up-to-date index of the Astro documentation.

Server Details

• Name: Astro Docs
• URL: https://mcp.docs.astro.build/mcp
• Transport: Streamable HTTP

This server uses streamable HTTP transport, which may not be compatible with all tools. Check your tool’s documentation for MCP support.

Installation

The setup process varies depending on your AI development tool. You may see some tools refer to MCP servers as connectors, adapters, extensions, or plugins.

Claude Code

Claude Code is an agentic coding tool that runs on the command line. Enabling the Astro Docs MCP server allows it to access the latest documentation while generating Astro code.

Install using the terminal command:

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

More info on using MCP servers with Claude Code

Cursor

Cursor is an AI code editor. Adding the Astro Docs MCP server allows Cursor to access the latest Astro documentation while performing development tasks.

Install by clicking the button below:

Add to Cursor

More info on using MCP servers with Cursor

Visual Studio Code

Visual Studio Code supports MCP servers when using Copilot Chat. Adding the Astro Docs MCP server allows VS Code to access the latest Astro documentation when answering questions or performing coding tasks.

Install by clicking the button below:

Add to VS Code

More info on using MCP servers with VS Code

Claude.ai / Claude Desktop

Claude.ai is a general-purpose AI assistant. Adding the Astro Docs MCP server allows it to access the latest documentation when answering Astro questions or generating Astro code.

1. Navigate to the Claude.ai connector settings.
2. Click “Add custom connector”. You may need to scroll down to find this option.
3. Enter the server URL: https://mcp.docs.astro.build/mcp.
4. Set the name to “Astro docs”.

More info on using MCP servers with Claude.ai

Windsurf

Windsurf is an AI-powered agentic coding tool, available as editor plugins or a standalone editor. It can use the Astro Docs MCP server to access documentation while performing coding tasks.

Windsurf doesn’t support streaming HTTP, so it requires a local proxy configuration:

1. Open ~/.codeium/windsurf/mcp_config.json in your editor.

2. Add the following configuration to your Windsurf MCP settings:

   MCP Configuration

   {
     "mcpServers": {
       "Astro docs": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
       }
     }
   }

3. Save the configuration and restart Windsurf.

More info on using MCP servers with Windsurf

ChatGPT

Limited availability

MCP server integration is only available for ChatGPT Pro, Team, and Enterprise users. The setup process is more complex than other tools.

Refer to the OpenAI MCP documentation for specific setup instructions.

Raycast

Raycast can connect to MCP servers to enhance its AI capabilities. AI features such as MCP require a Raycast Pro account, so ensure you have upgraded before trying to install. Adding the Astro Docs MCP server allows Raycast to access the latest Astro documentation while answering questions.

Install by clicking the button below:

Add to Raycast

More info on using MCP servers with Raycast

Usage

Once configured, you can ask your AI tool questions about Astro, and it will retrieve information directly from the latest docs. Coding agents will be able to consult the latest documentation when performing coding tasks, and chatbots will be able to accurately answer questions about Astro features, APIs, and best practices.

Remember

The Astro Docs MCP server provides access to current documentation, but your AI tools are still responsible for interpretation and code generation. AI makes mistakes, so always review generated code carefully and test thoroughly.

Troubleshooting

If you encounter issues:

• Verify that your tool supports streamable HTTP transport.
• Check that the server URL is correct: https://mcp.docs.astro.build/mcp.
• Ensure your tool has proper internet access.
• Consult your specific tool’s MCP integration documentation.

If you are still having problems, open an issue in the Astro Docs MCP Server repository.

Discord AI Support

The same technology that powers Astro’s MCP server is also available as a chatbot in the Astro Discord for self-serve support. Visit the #support-ai channel to ask questions about Astro or your project code in natural language. Your conversation is automatically threaded, and you can ask an unlimited number of follow-up questions.

Conversations with the chatbot are public, and are subject to the same server rules for language and behavior as the rest of our channels, but they are not actively visited by our volunteer support members. For assistance from the community, please create a thread in our regular #support channel.

Tips for AI-Powered Astro Development

• Start with templates: Rather than building from scratch, ask AI tools to start with an existing Astro template or use npm create astro@latest with a template option.
• Use astro add for integrations: Ask AI tools to use astro add for official integrations (e.g. astro add tailwind, astro add react). For other packages, install using the command for your preferred package manager rather than editing package.json directly.
• Verify current APIs: AI tools may use outdated patterns. Ask them to check the latest documentation, especially for newer features like sessions and actions. This is also important for features that have seen significant changes since their initial launch, such as content collections, or previously experimental features that may no longer be experimental.
• Use project rules: If your AI tool supports it, set up project rules to enforce best practices and coding standards, such as the ones listed above.