Skip to main content
The Aspect documentation is served through a hosted Model Context Protocol (MCP) 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:
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:
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.
Use the site.aspect.build host exactly. The docs are also reachable at aspect.build, and that host answers MCP requests, but the server’s OAuth resource is site.aspect.build. Clients that validate the protected-resource identifier reject the mismatch during authorization, so anything needing customer documentation must use site.aspect.build.

​
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:
Verify with:

​
Codex CLI

Add the server to ~/.codex/config.toml:
Authorize the server:
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:

​
VS Code

Create .vscode/mcp.json in your workspace with:
See the VS Code MCP documentation 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 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.