crate · amotl · Nov 3, 2025 · Nov 3, 2025 · Nov 3, 2025 · Nov 3, 2025
diff --git a/README.md b/README.md
diff --git a/docs/_links.md b/docs/_links.md
@@ -0,0 +1,21 @@
+[Add an MCP server to your VS Code user settings]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-user-settings
+[Add an MCP server to your VS Code workspace]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server-to-your-workspace
+[Automatic discovery of MCP servers]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_automatic-discovery-of-mcp-servers
+[CrateDB]: https://cratedb.com/database
+[CrateDB & MCP]: https://cratedb.com/docs/guide/integrate/mcp/
+[CrateDB MCP server OCI images]: https://github.com/orgs/crate/packages?repo_name=cratedb-mcp
+[cratedb-about]: https://pypi.org/project/cratedb-about/
+[cratedb-outline.yaml]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/outline/cratedb-outline.yaml
+[create a read-only database user by using "GRANT DQL"]: https://community.cratedb.com/t/create-read-only-database-user-by-using-grant-dql/2031
+[Docker Hub MCP Server]: https://www.docker.com/blog/introducing-docker-hub-mcp-server/
+[example questions]: https://github.com/crate/about/blob/v0.0.4/src/cratedb_about/query/model.py#L17-L44
+[examples folder]: https://github.com/crate/cratedb-mcp/tree/main/examples
+[LibreChat and MCP]: https://www.librechat.ai/docs/features/agents#model-context-protocol-mcp
+[LibreChat MCP examples]: https://www.librechat.ai/docs/configuration/librechat_yaml/object_structure/mcp_servers
+[MCP]: https://modelcontextprotocol.io/introduction
+[MCP clients]: https://modelcontextprotocol.io/clients
+[mcp hub]: https://hub.docker.com/mcp
+[MCP support for Open WebUI]: https://docs.openwebui.com/openapi-servers/mcp/
+[MCP-to-OpenAPI proxy server (mcpo)]: https://github.com/open-webui/mcpo
+[MCP tools]: https://modelcontextprotocol.io/docs/concepts/tools
+[using Goose extensions]: https://block.github.io/goose/docs/getting-started/using-extensions/
diff --git a/docs/configure/index.md b/docs/configure/index.md
@@ -0,0 +1,105 @@
+(configure)=
+
+# Configuration
+
+## Configure database connectivity
+
+Configure the `CRATEDB_CLUSTER_URL` environment variable to match your CrateDB instance.
+For example, when connecting to CrateDB Cloud, use a value like
+`https://admin:[email protected]:4200/`.
+When connecting to CrateDB on localhost, use `http://localhost:4200/`.
+```shell
+export CRATEDB_CLUSTER_URL="https://<username>:<password>@<example>.aks1.westeurope.azure.cratedb.net:4200"
+```
+```shell
+export CRATEDB_CLUSTER_URL="http://crate:crate@localhost:4200/"
+```
+
+The `CRATEDB_MCP_HTTP_TIMEOUT` environment variable (default: 30.0) defines
+the timeout for HTTP requests to CrateDB and its documentation resources
+in seconds.
+
+The `CRATEDB_MCP_DOCS_CACHE_TTL` environment variable (default: 3600) defines
+the cache lifetime for documentation resources in seconds.
+
+## Configure transport
+
+MCP servers can be started using different transport modes. The default transport
+is `stdio`, you can select another one of `{"stdio", "http", "sse", "streamable-http"}`
+and supply it to the invocation like this:
+```shell
+cratedb-mcp serve --transport=stdio
+```
+NB: The `http` transport was called `streamable-http` in earlier spec iterations.
+
+When using any of the HTTP-based options for serving the MCP interface, you can
+use the CLI options `--host`, `--port` and `--path` to specify the listening address.
+The default values are `localhost:8000`, where the SSE server responds to `/sse/`
+and `/messages/` and the HTTP server responds to `/mcp/` by default.
+
+Alternatively, you can use environment variables instead of CLI options.
+```shell
+export CRATEDB_MCP_TRANSPORT=http
+export CRATEDB_MCP_HOST=0.0.0.0
+export CRATEDB_MCP_PORT=8000
+```
+```shell
+export CRATEDB_MCP_PATH=/path/in/url
+```
+
+## Security considerations
+
+If you want to prevent agents from modifying data, i.e., permit `SELECT` statements
+only, it is recommended to [create a read-only database user by using "GRANT DQL"].
+```sql
+CREATE USER "read-only" WITH (password = 'YOUR_PASSWORD');
+GRANT DQL TO "read-only";
+```
+Then, include relevant access credentials in the cluster URL.
+```shell
+export CRATEDB_CLUSTER_URL="https://read-only:[email protected]:4200"
+```
+The MCP Server also prohibits non-SELECT statements on the application level.
+All other operations will raise a `PermissionError` exception, unless the
+`CRATEDB_MCP_PERMIT_ALL_STATEMENTS` environment variable is set to a
+truthy value.
+
+## System prompt customizations
+
+The CrateDB MCP server allows users to adjust the system prompt by either
+redefining the baseline instructions or extending them with custom conventions.
+Additional conventions can capture domain-specific details—such as information
+required for particular ER data models —- or any other guidelines you develop
+over time.
+
+If you want to **add** custom conventions to the system prompt,
+use the `--conventions` option.
+```shell
+cratedb-mcp serve --conventions="conventions-custom.md"
+```
+
+If you want to **replace** the standard built-in instructions prompt completely,
+use the `--instructions` option.
+```shell
+cratedb-mcp serve --instructions="instructions-custom.md"
+```
+
+Alternatively, use the `CRATEDB_MCP_INSTRUCTIONS` and `CRATEDB_MCP_CONVENTIONS`
+environment variables instead of the CLI options.
+
+To retrieve the standard system prompt, use the `show-prompt` subcommand. By
+redirecting the output to a file, you can subsequently edit its contents and
+reuse it with the MCP server using the command outlined above.
+```shell
+cratedb-mcp show-prompt > instructions-custom.md
+```
+
+Instruction and convention fragments can be loaded from the following sources:
+
+- HTTP(S) URLs
+- Local file paths
+- Standard input (when fragment is "-")
+- Direct string content
+
+Because LLMs understand Markdown well, you should also use it for writing
+personal instructions or conventions.
diff --git a/docs/index.md b/docs/index.md
@@ -1,13 +1,106 @@
+:::{include} _links.md
+:::
+
 (index)=
+
 # CrateDB MCP Server
 
 :::{include} readme.md
 :start-line: 1
+:end-line: 79
+:::
+
+:::{note}
+**Experimental:** Please note that the CrateDB MCP Server is an experimental
+feature provided as-is without warranty or support guarantees. Enterprise
+customers should use this feature at their own discretion.
+:::
+
+## Quickstart Guide
+
+:::{div}
+The CrateDB MCP Server is compatible with AI assistants that support the Model
+Context Protocol (MCP), either using standard input/output (`stdio`),
+server-sent events (`sse`), or HTTP Streams (`http`, earlier `streamable-http`).
+
+To use the MCP server, you need a [client that supports][MCP clients] the
+protocol. The most notable ones are ChatGPT, Claude, Cline Bot, Cursor,
+GitHub Copilot, Mistral AI, OpenAI Agents SDK, Windsurf, and others.
+:::
+
+This section includes detailed information about how to configure and
+operate the CrateDB MCP Server.
+
+::::{grid} 2 2 2 3
+:gutter: 2
+
+:::{grid-item-card} {material-regular}`download;2em` &nbsp; Install
+:link: install
+:link-type: ref
+:::
+
+:::{grid-item-card} {material-regular}`display_settings;2em` &nbsp; Configure
+:link: configure
+:link-type: ref
+:::
+
+:::{grid-item-card} {material-regular}`menu_book;2em` &nbsp; Use
+:link: usage
+:link-type: ref
+:::
+
+::::
+
+## What's inside
+
+:::{div}
+This section includes information about the included [MCP tools].
+
+Tools are a powerful primitive in the Model Context Protocol (MCP) that enable
+servers to expose executable functionality to clients. Through tools, LLMs can
+interact with external systems, perform computations, and take actions in the
+real world.
+:::
+
+The CrateDB MCP Server provides two families of tools.
+
+:::{div}
+
+:Text-to-SQL:
+
+  The tools `query_sql`, `get_table_columns`, and `get_table_metadata`
+  talk to a CrateDB database cluster to inquire database
+  and table metadata, and table content.
+
+:Documentation server:
+
+  The tools `get_cratedb_documentation_index` and `fetch_cratedb_docs`
+  look up guidelines specific to CrateDB topics,
+  to provide the most accurate information possible.
+  Relevant information is pulled from <https://cratedb.com/docs>, curated per
+  [cratedb-outline.yaml] through the [cratedb-about] package.
+
+:Health inquiry:
+
+  The tool `get_cluster_health` returns cluster health information derived
+  from CrateDB's system tables.
+:::
+
+
+:::{toctree}
+:caption: Handbook
+:maxdepth: 1
+:hidden:
+
+install/index
+configure/index
+usage/index
 :::
 
 :::{toctree}
 :caption: Workbench
 :maxdepth: 1
+:hidden:
 
 Changelog <changes>
 Sandbox <sandbox>

diff --git a/docs/install/index.md b/docs/install/index.md
@@ -0,0 +1,53 @@
+(install)=
+
+# Installation
+
+::::{grid} 2 2 2 2
+:gutter: 2
+
+:::{grid-item-card} {octicon}`package;2em` &nbsp; Package
+:link: install-package
+:link-type: ref
++++
+Install the `cratedb-mcp` package using `pipx` or `uv`,
+suitable for running as standalone service.
+:::
+
+:::{grid-item-card} {material-outlined}`integration_instructions;2em` &nbsp; Integrate
+:link: integrate
+:link-type: ref
++++
+Integrate CrateDB MCP with standard AI applications
+like Claude, Cline, Cursor, Roo Code, or Windsurf.
+:::
+
+:::{grid-item-card} {octicon}`container;2em` &nbsp; OCI
+:link: install-oci
+:link-type: ref
++++
+OCI images for Docker or Podman are available on GHCR.
+
+Image: `ghcr.io/crate/cratedb-mcp`
+:::
+
+:::{grid-item-card} {octicon}`star;2em` &nbsp; MCPO
+:link: install-mcpo
+:link-type: ref
++++
+The CrateDB MCPO OCI image supports Open WebUI out of the box.
+
+Image: `ghcr.io/crate/cratedb-mcpo`
+:::
+
+::::
+
+:::{toctree}
+:caption: Get started
+:maxdepth: 1
+:hidden:
+
+package
+integrate
+OCI <oci>
+MCPO <mcpo>
+:::