> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# How to connect an AI assistant with MCP

> Connect Claude, Claude Code, Codex, Cursor, or VS Code to the Aspect docs MCP server so your AI assistant can search and cite Aspect documentation.

The Aspect documentation is served through a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server. Connecting your AI coding assistant to it lets the assistant search and read the Aspect docs directly while it works in your repo instead of guessing from training data or a generic web search.

This is particularly useful for tasks like migrating YAML tasks to AXL, extending Gazelle in Starlark, upgrading Aspect Workflows, or wiring up the Aspect CLI in CI. In each case, the assistant can pull the exact, current instructions from these docs.

## MCP server URLs

For interactive AI assistants, use the authenticated endpoint:

```text theme={null}
https://site.aspect.build/authed/mcp
```

This endpoint requires a one-time OAuth authorization. Signing in with an Aspect account that has customer documentation access makes the full installation and configuration documentation available in addition to the public pages.

For anonymous access to public pages only, use:

```text theme={null}
https://site.aspect.build/mcp
```

The anonymous endpoint doesn't start an OAuth flow, so configuring it in an interactive client limits that client to public documentation. It is useful for automation that doesn't need customer documentation. Documentation search and retrieval are read-only; the server also exposes an optional tool for submitting documentation feedback.

<Info>
  Use the <code>site.aspect.build</code> host exactly. The docs are also reachable at <code>aspect.build</code>, and that host answers MCP requests, but the server's OAuth resource is <code>site.aspect.build</code>. Clients that validate the protected-resource identifier reject the mismatch during authorization, so anything needing customer documentation must use <code>site.aspect.build</code>.
</Info>

## Quick copy from any docs page

Every page on this site exposes a contextual menu (top of the page) with one-click options to:

* **Copy MCP Server:** Copies the anonymous public endpoint to your clipboard.
* **Connect to Cursor:** Installs the anonymous public endpoint in Cursor.
* **Connect to VS Code:** Installs the anonymous public endpoint in VS Code.

These shortcuts always use the anonymous `/mcp` endpoint on whichever host you are browsing. On `aspect.build` they yield `https://aspect.build/mcp`, which cannot be authorized — see the note above. For customer documentation, set the URL to `https://site.aspect.build/authed/mcp` by hand and complete the OAuth authorization.

## Connect from common clients

### Claude Desktop

1. Open **Settings → Connectors** in Claude.
2. Click **Add custom connector**.
3. Set the name to `Aspect Docs` and the URL to `https://site.aspect.build/authed/mcp`.
4. Click **Add**.
5. Complete the OAuth authorization with your Aspect account.
6. In a Claude chat, click the attachments (+) button and select **Aspect Docs** to give that thread access to the Aspect docs.

### Claude Code

Run once from your terminal:

```shell theme={null}
claude mcp add --transport http aspect-docs https://site.aspect.build/authed/mcp
claude mcp login aspect-docs
```

Verify with:

```shell theme={null}
claude mcp list
```

### Codex CLI

Add the server to `~/.codex/config.toml`:

```toml theme={null}
[mcp_servers.aspect-docs]
url = "https://site.aspect.build/authed/mcp"
```

Authorize the server:

```shell theme={null}
codex mcp login aspect-docs
```

Then start a Codex session and ask *"What tools do you have available?"* The `aspect-docs` server should be listed.

### Cursor

1. Open the command palette with `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows/Linux).
2. Run **Open MCP settings**.
3. Click **Add custom MCP** and add the following to `mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "aspect-docs": {
      "url": "https://site.aspect.build/authed/mcp"
    }
  }
}
```

### VS Code

Create `.vscode/mcp.json` in your workspace with:

```json theme={null}
{
  "servers": {
    "aspect-docs": {
      "type": "http",
      "url": "https://site.aspect.build/authed/mcp"
    }
  }
}
```

See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for details on scope and permissions.

## What the assistant can do with it

Once connected, the assistant can:

* **Search** the Aspect docs across the CLI, Aspect Workflows, AXL reference, and Bazel guides.
* **Fetch full pages** as Markdown when it needs the complete instructions (for example, an upgrade guide or a migration walk-through).
* **Cite the page it used**, so you can jump to the source directly.

Search covers more pages than full-page retrieval does. Parts of the generated AXL reference are reachable through search results and on the web, but cannot be fetched as whole pages; for those, follow the link in the citation.

This pairs well with letting an assistant drive larger changes. For example, the [migration docs](/docs/cli/migration) explicitly recommend pointing an AI coding assistant at them to handle the bulk of a YAML-to-AXL conversion.

## Troubleshooting

* **The tool doesn't appear after adding it.** Restart the AI client after editing `mcp.json` / `config.toml`. Most clients only load MCP servers at startup.
* **The client can search public docs but can't find customer docs.** Check that it uses `https://site.aspect.build/authed/mcp`, then complete the client's OAuth login. The `/mcp` endpoint is anonymous and public-only.
* **The client reports 401, 405, or "method not allowed" when opening the URL in a browser.** That's expected: the MCP endpoints respond to MCP protocol requests, not plain `GET` requests. Configure the URL in your MCP client instead of visiting it directly.
* **Authentication fails with a protected-resource mismatch.** Your client is configured with the wrong host (usually `aspect.build/mcp`). Use `https://site.aspect.build/authed/mcp` exactly because its origin matches the server's OAuth resource.
* **You want to script MCP calls in CI.** Use `https://site.aspect.build/mcp` for anonymous access to public documentation. Accessing customer documentation requires an authenticated session through `https://site.aspect.build/authed/mcp`.