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 <[email protected]> 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.
