Docs MCP Server (AI Coding Agents)

ToolsMCPAI AgentsClaude CodeCursorVS Code

Stable On by default · production-ready

What it is

The AetheriusDB docs MCP server is a hosted Model Context Protocol endpoint that serves this entire documentation set to an AI coding agent as a set of callable tools.

https://aetheriusdb.com/mcp

It is public, needs no API key or account, and speaks the Streamable HTTP transport — so any MCP-capable client can connect with one command or a three-line config file.

Why it matters

Large language models were trained before AetheriusDB existed. Ask one to write Aetherius SQL and it will confidently produce PostgreSQL instead — upsert clauses, vector-distance operators, and vacuum and extension statements that this engine does not accept. AetheriusDB speaks the Postgres wire protocol, but its dialect and feature set genuinely differ, so that code fails at runtime and your agent burns a round-trip discovering it.

With this server connected, the agent looks the answer up instead:

Ground truth, not recall — it reads the same pages you do, at the version currently published.
Availability is machine-readable — every result carries a [stable], [opt-in], [beta], or [roadmap] tag, so the agent can tell a shipped feature from a planned one before it writes code against it. This is the single most valuable signal in the corpus.
No hallucinated Postgres — the bundled sql_cheatsheet prompt front-loads the dialect traps before a line of SQL gets written.

Add it to your editor

Pick your client. Each of these is complete on its own — you do not need to install anything, clone this repo, or run a local process.

Claude Code

One command, from anywhere:

claude mcp add --transport http aetherius-docs https://aetheriusdb.com/mcp

By default this registers the server for the current project only, private to you. Add a --scope flag to change that:

Scope	Flag	Stored in	Who gets it
Local (default)	`--scope local`	`~/.claude.json`	Just you, this project
Project	`--scope project`	`.mcp.json` in the repo root	Everyone who checks out the repo
User	`--scope user`	`~/.claude.json`	Just you, every project

--scope project is the one to use on a team: it writes a .mcp.json you commit, so every engineer and every CI agent on the repo gets the same documentation without being told to configure anything.

{
  "mcpServers": {
    "aetherius-docs": {
      "type": "http",
      "url": "https://aetheriusdb.com/mcp"
    }
  }
}

Verify it connected with /mcp inside a session, or claude mcp list from the shell. The tools appear namespaced as mcp__aetherius-docs__aetherius_docs_search and friends — that is the form to use if you want to pre-approve them in a permissions rule.

Cursor

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json to enable it in every project):

{
  "mcpServers": {
    "aetherius-docs": {
      "url": "https://aetheriusdb.com/mcp"
    }
  }
}

Remote servers in Cursor are identified by the url field alone — there is no type key to set. Then open Customize in the sidebar, find aetherius-docs, and make sure its toggle is on.

VS Code

Create .vscode/mcp.json in your workspace:

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

To install it into your user profile instead of one workspace, run MCP: Open User Configuration from the Command Palette and add the same servers entry there.

Confirm with MCP: List Servers in the Command Palette. In an agent-mode chat, click Configure Tools to see the three aetherius_docs_* tools and toggle them on.

What your agent gets

Three tools and two prompts.

Tool	What it returns
`aetherius_docs_index`	The full table of contents — every page’s title, slug, one-line description, and availability status, grouped by section. The orientation call.
`aetherius_docs_search`	Keyword (BM25) search across the docs, the knowledge base, the Python client reference, and the implementation-status trackers. Returns excerpts with slug, section, and availability.
`aetherius_docs_get_page`	The full markdown of one page by slug, with an optional `heading:` argument to fetch a single section.

Prompt	When to load it
`sql_cheatsheet`	Before writing any SQL for AetheriusDB — the condensed list of Postgres habits that break here, the declarable types, and the function-based vector-search syntax.
`python_quickstart`	Before writing Python client code — connect, query, prepare, transact, bulk-load.

Search is lexical, not semantic, by design. Queries against a database corpus are identifier-heavy — TENSOR_COSINE, USING HNSW, PULSE, FOR SYSTEM_TIME AS OF — and exact-token BM25 beats embedding similarity on that shape of query, while keeping the server dependency-free and instant to rebuild when the docs change.

Check that it works

Once connected, ask your agent a question whose answer it cannot know:

Which AetheriusDB features are still roadmap-only rather than stable?

A correctly wired agent calls aetherius_docs_index or aetherius_docs_search and answers with the real availability tags. If it answers instantly from general knowledge with no tool call, the server isn’t connected — recheck the config file name and the top-level key.

You can also probe the endpoint directly. MCP’s Streamable HTTP transport requires both content types in the Accept header:

curl -s -X POST https://aetheriusdb.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18","capabilities":{},
                 "clientInfo":{"name":"curl","version":"1"}}}'

A healthy server replies with its serverInfo block. A 406 means your Accept header was missing text/event-stream — that is the transport working as specified, not an outage.

Run it locally instead

The server is open source and ships in the AetheriusDB repository at mcp-servers/docs-mcp. Running your own copy is worth it if you work offline, or if you want the agent reading documentation from your checkout — including any local edits — rather than the published site. It needs Node 20+ and has no build step.

cd mcp-servers/docs-mcp
npm ci
npm run stdio        # stdio transport, for an editor to spawn
npm start            # or HTTP on 127.0.0.1:8091

Point any client that can spawn a process at it:

{
  "mcpServers": {
    "aetherius-docs": {
      "command": "node",
      "args": ["/path/to/repo/mcp-servers/docs-mcp/src/server.js", "--stdio"],
      "env": { "DOCS_ROOT": "/path/to/repo/Aetherius-docs" }
    }
  }
}

DOCS_ROOT is required and must point at the Aetherius-docs directory. The optional KB_ROOT, PY_README_PATH, and TRACKER_PATHS variables add the knowledge base, the Python client reference, and the implementation-status trackers to the search corpus; see mcp-servers/docs-mcp/.env.example for the full list.

Troubleshooting

Server shows as failed or never appears. Check the top-level key: it is servers for VS Code and mcpServers for Claude Code and Cursor. This is the single most common mistake.
Claude Code reports a configuration error. A hand-written .mcp.json entry needs "type": "http" alongside "url".
The agent answers without calling a tool. In VS Code, tools must be enabled per-chat under Configure Tools; in Cursor, the server must be toggled on under Customize.
Curl returns 406. Add text/event-stream to the Accept header — see above.

SQL Grammar & Types →

The SQL surface the agent will be reading — types, CTEs, window functions, NULL rules.

Configuration & Availability →

Which features are on by default and which are behind a flag.

Connect a Client →

Once the agent knows the dialect, point your application at the database.

aesql — SQL CLI →

Run what the agent writes, from a psql-style REPL.