> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alginte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect AI agents to Alginte: a built-in MCP server with read-only Kafka inspection tools, and in the playground's sandbox mode, tools that validate, deploy and stop streams.

Alginte ships a built-in [Model Context Protocol](https://modelcontextprotocol.io) server:
AI agents (Claude Code, Claude Desktop, and any other MCP client) can inspect your Kafka
cluster through the same service layer the UI uses — list and describe topics, read
consumer-group lag, check connectors and schemas, and sample messages.

> [!NOTE]
>
> Requires Alginte **0.6.0** or newer, included in the free Community edition. Every tool is
> read-only by default. In [sandbox mode](#sandbox-mode-the-stream-tools), an isolated stack
> like the playground, the stream tools can also deploy, stop and delete streams. Never turn
> sandbox mode on against a shared cluster.

## Endpoint

The server speaks **Streamable HTTP** at `/mcp` on the regular application port — same
process, same port, same network reachability as the UI:

```text theme={null}
http://localhost:8888/mcp
```

There is nothing to enable — it is on by default. To switch the whole surface off:

```shell theme={null}
-e SPRING_AI_MCP_SERVER_ENABLED=false
```

## Connecting a client

### Claude Code

```shell theme={null}
claude mcp add --transport http alginte http://localhost:8888/mcp
```

### Claude Desktop

Settings → Connectors → **Add custom connector**, with the same URL.

### With authentication enabled

If the optional [login](https://docs.alginte.com/operate/authentication.md) is on, `/mcp` requires the same
credentials over **HTTP Basic** — MCP clients send them as a header:

```shell theme={null}
claude mcp add --transport http alginte http://localhost:8888/mcp \
  --header "Authorization: Basic $(echo -n 'admin:<password>' | base64)"
```

> [!WARNING]
>
> With an **OIDC-only** login there is no header credential an MCP client can send. To
> use MCP on an OIDC-protected instance, also configure the username/password login —
> or keep the instance inside its network boundary with the login off.

## Tools

By default every tool is read-only (`readOnlyHint`) and honors the same settings as the
REST API — for example, sensitive config values stay masked unless the operator enabled
`ALGINTE_SHOWSENSITIVECONFIG`. An instance in [sandbox mode](#sandbox-mode-the-stream-tools)
adds the tools that deploy and reset stream designs.

| Tool | What it returns |
| - | - |
| `get_cluster_info` | Cluster id, controller, broker count |
| `list_brokers` | Brokers with host, port, controller flag |
| `get_broker_config` | One broker's configuration entries |
| `list_topics` | Topics with partition and replica counts |
| `describe_topic` | One topic's partitions, leaders, replicas, ISR |
| `get_topic_partitions` | Per-partition earliest and latest offsets |
| `get_topic_config` | One topic's configuration entries |
| `list_consumer_groups` | All consumer groups with type and state |
| `describe_consumer_group` | Members plus per-partition committed offset, end offset, and lag |
| `get_connect_cluster` | Kafka Connect cluster info |
| `list_connectors` | Connectors with status, tasks, and config |
| `get_connector_details` | One connector's full status and config |
| `list_schema_subjects` | Schema Registry subjects with latest-version summary |
| `get_schema_subject` | One subject: latest schema, versions, compatibility |
| `get_schema_version` | One specific schema version's text |
| `list_streams` | Kafka Streams apps registered in this Alginte instance |
| `describe_stream` | One stream's state, flags, topology description and failure; the metrics and the design JSON on request (`includeMetrics`, `includeDesign`) |
| `consume_messages` | A bounded sample of messages from a topic |

The Connect and Schema Registry tools need their upstream URLs
[configured](https://docs.alginte.com/operate/configuration.md), exactly like the corresponding UI areas.

### Sampling messages

`consume_messages` fetches up to 500 messages (default 20) without joining a consumer
group or committing anything — it never affects your applications. The `seekType`
argument picks the window: `Newest` (default), `Oldest`, `OffsetGE` / `OffsetLE` (from
an offset), `After` / `Before` (from a timestamp). Key and value deserializers default
to `String`; `JSON`, numeric types, `Bytes`, and the Schema-Registry-backed
`JSONSchema` / `Avro` / `Protobuf` are available.

## Sandbox mode: the stream tools

The [playground](https://docs.alginte.com/installation/playground.md) runs Alginte in **sandbox mode**
(`alginte.sandbox.enabled=true`): its stack is nobody's shared cluster, and everything an
agent does there is undone by `docker compose down`. In that mode the MCP endpoint also
offers the tools an agent needs to work the Streams builder the way a person does: propose a
design, read what the deploy gate refuses, deploy, watch, and start over.

| Tool | What it does |
| - | - |
| `validate_topology` | Runs the deploy gate over a design (the JSON the builder downloads) without deploying it: the topology rules, missing source topics or subjects, join inputs that are not co-partitioned, an id already deployed here, and the residue an earlier deployment left on the cluster. It also returns the [Enrich node's throughput warnings](https://docs.alginte.com/streams/enrich.md#throughput-and-the-poll-loop), each naming the stream property and the value that quiets it, and the calls each Enrich node can have in flight. A warning never refuses a deploy. |
| `deploy_topology` | The same gate, then the deploy and the start. Refusals come back as problems; residue on the id comes back as a question answered with `onResidue=continue` or `fresh`. The gate's warnings come back whether it deploys or not. |
| `evaluate_expression` | The [sample preview](https://docs.alginte.com/streams/spel.md#the-sample-preview) as a tool: a chain of SpEL steps evaluated against one record, from a topic's newest record or a sample you pass, with each step's output and shape, or the error on the step that failed. An [Enrich](https://docs.alginte.com/streams/enrich.md) step takes a simulated answer and never calls the service; its note says the answer was simulated. |
| `stop_stream`, `delete_stream` | The lifecycle actions of the detail page; delete takes the state with it on request and reports what it removed. |

The mutating tools carry `destructiveHint`; MCP clients that confirm destructive calls will
ask before each. They answer refusals as data, never as tool errors, so an agent can read
the reason and try again, and the preview it reasons from is the one the fidelity corpus
holds to the deployed runtime.

> [!WARNING]
>
> Sandbox mode is for an isolated stack only. Never set `alginte.sandbox.enabled=true` on an
> instance that runs against a shared cluster: the tools deploy, stop and delete streams and
> can remove their state from that cluster. Sandbox mode is a Community capability;
> mutation against a shared cluster is not part of it.

## Security notes

The MCP endpoint binds like every other route — it is inside the same
[deployment boundary](https://docs.alginte.com/operate/production.md) as the UI, and the login (when enabled)
covers it. One consideration specific to agents: content an agent reads from Kafka
(message payloads, connector configs, schema documents) is untrusted input to that
agent's context. Outside sandbox mode the read-only tool design bounds the blast radius —
there is nothing destructive an injected instruction could call — and in sandbox mode the
blast radius is the isolated stack itself. Review your MCP client's own confirmation
settings before pointing agents at sensitive clusters.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.