(iggy-website) 06/13: fix(docs): align MCP setup and permissions

[hg...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

hubcio pushed a commit to branch docs/align-with-topic-durability
in repository https://gitbox.apache.org/repos/asf/iggy-website.git

commit 2d570fa75d1df3540adf90cf2fa7ad9132913776
Author: hubcio <h....@gmail.com>
AuthorDate: Fri Sep 11 04:24:43 2026 +0200

    fix(docs): align MCP setup and permissions
---
 content/docs/ai/mcp.mdx | 51 +++++++++++++++++++++++++++++++++++++------------
 1 file changed, 39 insertions(+), 12 deletions(-)

diff --git a/content/docs/ai/mcp.mdx b/content/docs/ai/mcp.mdx
index 8e8e716b..201150e7 100644
--- a/content/docs/ai/mcp.mdx
+++ b/content/docs/ai/mcp.mdx
@@ -7,9 +7,15 @@ The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open p
 
 ## Getting started
 
-To start the MCP server, simply run `cargo run --bin iggy-mcp`.
+Start an Iggy 0.9.0 or edge broker using the [getting started guide](/docs/introduction/getting-started). From the matching `apache/iggy` checkout, run:
 
-The [docker image](https://hub.docker.com/r/apache/iggy-mcp) is available, and can be fetched via `docker pull apache/iggy-mcp`.
+```bash
+IGGY_MCP_IGGY_USERNAME=iggy IGGY_MCP_IGGY_PASSWORD=iggy cargo run --bin iggy-mcp
+```
+
+These are the development credentials configured in that guide. Use your broker's credentials or a PAT when connecting to an existing installation.
+
+The [docker image](https://hub.docker.com/r/apache/iggy-mcp) is available, and can be fetched via `docker pull apache/iggy-mcp:edge`.
 
 ## Configuration
 
@@ -68,13 +74,15 @@ transport = "grpc" # grpc or http
 endpoint = "http://localhost:4317"
 ```
 
-The configuration file must be in the `toml` format. The path to the configuration can be overridden by `IGGY_MCP_CONFIG_PATH` environment variable. Each setting can also be overridden by using the following convention `IGGY_MCP_<SECTION>_<KEY>` e.g. `IGGY_MCP_IGGY_USERNAME`, `IGGY_MCP_HTTP_ADDRESS` and so on. Environment variables can also be loaded from a dotenv file: point `IGGY_MCP_ENV_PATH` at the file, otherwise a `.env` file in the current working directory is loaded automatically.
+The configuration file must be in the `toml` format. By default, the server looks for `core/ai/mcp/config.toml` relative to its working directory. Set `IGGY_MCP_CONFIG_PATH` to use another path. Embedded defaults are loaded first, then the file if it exists, then environment overrides.
+
+Each setting can also be overridden using `IGGY_MCP_<SECTION>_<KEY>`, for example `IGGY_MCP_IGGY_USERNAME` or `IGGY_MCP_HTTP_ADDRESS`. Nested settings use the same underscore convention, such as `IGGY_MCP_IGGY_TLS_ENABLED`. Set `IGGY_MCP_ENV_PATH` to load a particular dotenv file; otherwise `.env` is searched for in the current directory and its parents. Existing environment variables take precedence over dotenv values.
 
-The `token` value can be either a literal PAT or a `file:` reference such as `token = "file:/run/secrets/iggy_pat"`, in which case the token is read from the given file (`~` is expanded to the home directory).
+The `token` value can be either a literal PAT or a `file:` reference such as `token = "file:/run/secrets/iggy_pat"`, in which case the token is read from the given file and surrounding whitespace is removed (`~/` is expanded to the home directory). A non-empty token takes precedence over the username and password.
 
 ## Available tools
 
-The MCP server exposes 40+ tools covering the full Iggy API:
+The MCP server exposes these 41 tools:
 
 ### Server
 
@@ -169,11 +177,13 @@ update = false
 delete = false
 ```
 
+`poll_messages` requires `update` as well as `read` when `auto_commit` is true or the `next` strategy is used. The `next` strategy enables auto-commit automatically. Storing an offset requires `update`; deleting an offset requires `delete`. PAT creation and deletion require `create` and `delete`, respectively.
+
 On top of this, the Iggy user account used by the MCP server has its own granular permissions. For production use, create a dedicated user with the minimum required permissions.
 
 ## Claude Desktop integration
 
-Here's the example configuration to be used with Claude Desktop:
+Set `command` to the absolute path of the built `iggy-mcp` executable. This Claude Desktop example uses the broker and development credentials from the getting started guide:
 
 ```json
 {
@@ -182,7 +192,10 @@ Here's the example configuration to be used with Claude Desktop:
       "command": "/path/to/iggy-mcp",
       "args": [],
       "env": {
-        "IGGY_MCP_TRANSPORT": "stdio"
+        "IGGY_MCP_TRANSPORT": "stdio",
+        "IGGY_MCP_IGGY_ADDRESS": "localhost:8090",
+        "IGGY_MCP_IGGY_USERNAME": "iggy",
+        "IGGY_MCP_IGGY_PASSWORD": "iggy"
       }
     }
   }
@@ -191,18 +204,32 @@ Here's the example configuration to be used with Claude Desktop:
 
 ## Docker
 
-Run the MCP server as a container:
+Create a shared network and start a development broker that advertises its container name:
 
 ```bash
-docker run -e IGGY_MCP_TRANSPORT=http \
+docker network create iggy-mcp
+docker run -d --name iggy-server --network iggy-mcp \
+  --security-opt seccomp=unconfined --ulimit memlock=-1:-1 \
+  -e IGGY_ROOT_USERNAME=iggy -e IGGY_ROOT_PASSWORD=iggy \
+  -e IGGY_TCP_ADDRESS=0.0.0.0:8090 \
+  -e IGGY_NODE_ADVERTISED_ADDRESS=iggy-server \
+  apache/iggy:edge
+```
+
+After the broker is ready, run the MCP server on the same network:
+
+```bash
+docker run --rm --network iggy-mcp -e IGGY_MCP_TRANSPORT=http \
   -e IGGY_MCP_HTTP_ADDRESS=0.0.0.0:8082 \
   -e IGGY_MCP_IGGY_ADDRESS=iggy-server:8090 \
   -e IGGY_MCP_IGGY_USERNAME=iggy \
   -e IGGY_MCP_IGGY_PASSWORD=iggy \
-  -p 8082:8082 \
-  apache/iggy-mcp
+  -p 127.0.0.1:8082:8082 \
+  apache/iggy-mcp:edge
 ```
 
+The HTTP endpoint uses the configured Iggy account for every MCP client. This example publishes it only on the host loopback interface.
+
 The default HTTP address is `127.0.0.1:8082`, which inside a container is unreachable from the outside, so `IGGY_MCP_HTTP_ADDRESS=0.0.0.0:8082` is required for the published port to work.
 
 ## Systemd integration
@@ -213,4 +240,4 @@ Build with the `systemd` cargo feature to enable systemd readiness and watchdog
 cargo build --bin iggy-mcp --release --features iggy-mcp/systemd
 ```
 
-The MCP server then behaves the same way the Iggy server does under systemd.
+Readiness is sent after the HTTP listener starts or the stdio MCP session initializes. When systemd enables the watchdog, the server sends keep-alive notifications at half the configured watchdog interval. SIGINT, SIGTERM, or stdio client disconnect stops the server and sends a stopping notification.