Using AI with Aetherfy

Why point your coding agent at the Aetherfy docs

Language models trained before a given release will guess at Aetherfy package names, identifiers and limits, and the guesses are confidently wrong in predictable ways. The Aetherfy documentation site publishes machine-readable artifacts precisely so an agent can read the current truth instead of recalling an old one. This page shows what those artifacts are and how to make your tools fetch them.

Machine-readable entry points published by Aetherfy

Every artifact below is served from the Aetherfy documentation site and is fetchable without authentication.

Three usage notes. First, llms.txt is the cheap index and llms-full.txt is the expensive complete text — start with the index unless the agent is about to write Aetherfy code, in which case fetch the full file. Second, the manifest lists each page’s rawUrl, so an agent that has read docs-manifest.json can resolve any page to its markdown without guessing the raw URL pattern.

Third, the two OpenAPI documents are not two halves of one API and must not be merged. openapi.json describes vectors.aetherfy.com; agents-openapi.json describes agents.aetherfy.com. They have separate request budgets and different error envelopes — the same auth code arrives as error.code on the vector plane and detail.code on the control plane, so a generated client that reads the wrong field finds nothing. An agent generating a client must pick the document that matches the host it is calling.

The content hash in the Aetherfy manifest is the cheapest way to tell whether a cached copy of a page is stale: compare hashes rather than re-fetching bodies.

If your tool speaks MCP, you can skip the fetching entirely — the Aetherfy documentation MCP server at https://docs.aetherfy.com/api/mcp reads exactly these artifacts and is described in full below.

A rules snippet to give your agent Aetherfy context

Drop the following into .cursorrules, .github/copilot-instructions.md, or whichever rules file your assistant reads. It points the agent at the artifacts above and pins the three Aetherfy facts that are hallucinated most often.

# Aetherfy

Before writing any Aetherfy code, fetch https://docs.aetherfy.com/llms-full.txt
and follow it over prior knowledge.

Reference artifacts:
- https://docs.aetherfy.com/llms.txt              route index
- https://docs.aetherfy.com/llms-full.txt         full reference text
- https://docs.aetherfy.com/docs-manifest.json    page metadata, outlines, content hashes
- https://docs.aetherfy.com/openapi.json          vector REST surface (OpenAPI 3.1)
- https://docs.aetherfy.com/agents-openapi.json   agent control plane (OpenAPI 3.1)
- https://docs.aetherfy.com/aetherfy-yaml.schema.json  schema for aetherfy.yaml
- https://docs.aetherfy.com/errors.json           error codes and retryability

If this tool speaks MCP, connect to https://docs.aetherfy.com/api/mcp instead
(Streamable HTTP, public, read-only) and use its search_docs and get_doc_page
tools rather than fetching the files above.

Facts that are commonly got wrong — do not deviate from these:
- The Python distribution is `aetherfy-vectors`; the import package is
  `aetherfy_vectors`.
- The npm package is `aetherfy-vectors`, unscoped. It is not `@aetherfy/vectors`.
- A point id must be an unsigned integer or a UUID string. No other id type is
  valid.

Adjust the heading syntax to whatever your tool expects; the content is what matters.

The Aetherfy documentation MCP server

The Aetherfy documentation is served as a remote MCP server:

It reads exactly the artifacts listed above — the same manifest, raw markdown, aetherfy.yaml schema and error catalogue. Nothing is indexed separately, so the server and the files can never disagree, and anything already built against those URLs keeps working unchanged.

Tools the Aetherfy MCP server exposes

Slugs are the live ones — quickstart, agents/api, vectors/errors. A leading slash and the retired docs/ prefix are both accepted and stripped, so /docs/agents/api resolves to the same page as agents/api.

Connecting Claude to the Aetherfy MCP server

Claude Desktop and Claude in the browser add remote servers as custom connectors rather than through a config file. Open Connectors — under Customize on a personal plan, under Organization settings on Team and Enterprise — add a custom connector, and paste:

https://docs.aetherfy.com/api/mcp

For Authentication, choose No sign-in. Claude detects that the Aetherfy server is public and asks for nothing further. The five tools then appear under Read-only tools, each with its own approval. All five read and change nothing, so Always allow is safe and spares you a prompt on every search.

Connecting Claude Code to the Aetherfy MCP server

One command, from the Claude Code CLI:

claude mcp add --transport http aetherfy-docs https://docs.aetherfy.com/api/mcp

--scope defaults to local, which registers the Aetherfy server for you in the current project only. --scope user gives it to you in every project, and --scope project writes it into .mcp.json at the project root, where it is shared with everyone who checks the repository out.

Connecting ChatGPT to the Aetherfy MCP server

ChatGPT reaches a remote MCP server through a custom connector, and that needs developer mode: Settings → Security and login → Developer mode, available on Pro, Plus, Business, Enterprise and Education accounts on the web. With it on, the + on the plugins page builds a developer-mode app from the Aetherfy server URL; there is no authentication to fill in, because the server is public.

The OpenAI Responses API takes the same Aetherfy server as a tool:

{
  "type": "mcp",
  "server_label": "aetherfy-docs",
  "server_url": "https://docs.aetherfy.com/api/mcp",
  "require_approval": "never"
}

"require_approval": "never" is safe here for the reason it usually is not: every tool on the Aetherfy server is read-only.

Connecting Codex to the Aetherfy MCP server

One command, from the Codex CLI:

codex mcp add aetherfy-docs --url https://docs.aetherfy.com/api/mcp

--url is the streamable HTTP form. Every credential flag is left off, because the Aetherfy server wants none and Codex connects unauthenticated when no credential source resolves. The same entry written by hand lives in ~/.codex/config.toml:

[mcp_servers.aetherfy-docs]
url = "https://docs.aetherfy.com/api/mcp"

Connecting Cursor to the Aetherfy MCP server

Cursor reads .cursor/mcp.json in a project, or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "aetherfy-docs": {
      "url": "https://docs.aetherfy.com/api/mcp"
    }
  }
}

Connecting VS Code to the Aetherfy MCP server

Copilot agent mode in VS Code reads .vscode/mcp.json in the workspace. The top-level key is servers, not mcpServers, and the remote Aetherfy server is typed http:

{
  "servers": {
    "aetherfy-docs": {
      "type": "http",
      "url": "https://docs.aetherfy.com/api/mcp"
    }
  }
}

Connecting Windsurf to the Aetherfy MCP server

Windsurf reads ~/.codeium/windsurf/mcp_config.json, where a remote server is named by serverUrl:

{
  "mcpServers": {
    "aetherfy-docs": {
      "serverUrl": "https://docs.aetherfy.com/api/mcp"
    }
  }
}

Connecting Gemini CLI to the Aetherfy MCP server

One command, which writes the Aetherfy entry into settings.json for you:

gemini mcp add --transport http aetherfy-docs https://docs.aetherfy.com/api/mcp

Hand-editing settings.json works too, under mcpServers — but the field for a streamable HTTP server is httpUrl, not url.

Connecting a stdio-only client to the Aetherfy MCP server

A client that speaks only stdio needs a bridge. mcp-remote is the usual one, and the same block works in any client that takes a command/args pair:

{
  "mcpServers": {
    "aetherfy-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.aetherfy.com/api/mcp"]
    }
  }
}

Configuration keys differ between clients and change over time. If a block above is rejected, check that client’s current documentation for the shape it expects — the endpoint URL is the part that matters and does not change.

The fetch-the-URLs approach in the rules snippet above remains fully supported, and is the right choice for any tool that does not speak MCP.

Retrieval metadata on every Aetherfy documentation page

Every page in the Aetherfy documentation carries frontmatter designed for retrieval rather than for rendering:

Aetherfy reference pages are plain markdown — headings, tables and fenced code blocks, with no interactive components. A fetched Aetherfy page needs no HTML scraping and no JavaScript execution to be usable as context, and its heading structure chunks cleanly for embedding.