> ## 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 exposes read-only Kafka inspection tools over Streamable HTTP.

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>
  Available from **0.6.0**. The MCP tool set is **read-only** and included in the free
  Community edition. Nothing on the MCP surface can create, delete, or modify anything.
</Note>

## 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](/operate/authentication) 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.
</Warning>

## Tools

All tools are read-only (`readOnlyHint`) and honor the same settings as the REST API —
for example, sensitive config values stay masked unless the operator enabled
`ALGINTE_SHOWSENSITIVECONFIG`.

| Tool                      | What it returns                                                  |
| ------------------------- | ---------------------------------------------------------------- |
| `get_cluster_info`        | Cluster id and feature versions                                  |
| `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, metrics, and topology description            |
| `consume_messages`        | A bounded sample of messages from a topic                        |

The Connect and Schema Registry tools need their upstream URLs
[configured](/operate/configuration), 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.

## Security notes

The MCP endpoint binds like every other route — it is inside the same
[deployment boundary](/operate/production) 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. The read-only tool design bounds the blast radius — there is nothing
destructive an injected instruction could call — but review your MCP client's own
confirmation settings before pointing agents at sensitive clusters.