# MCP Server

The Lenses MCP ([Model Context Protocol)](https://modelcontextprotocol.io/docs/getting-started/intro) Server extends Lenses to your AI tools and agents, bringing the power of Kafka data exploration, transformation, and integration to Claude, Cursor and other AI applications.

Instead of manually querying Kafka topics, managing connectors, or exploring environments through the UI, you can now use natural language to interact with your Kafka infrastructure directly from your AI tool.

### What is MCP

**Model Context Protocol** (MCP) is an open standard that allows AI models and agents to safely interact with external systems. The Lenses MCP Server implements this protocol, giving your AI assistant direct access to Lenses capabilities.

### Key Concepts

* **MCP Client**: Your AI tool (Claude, Cursor, Codex, etc.) that initiates requests and displays results. The client automatically handles authentication and discovers available capabilities from the MCP server.
* **MCP Server**: The Lenses MCP Server acts as a bridge between your AI tool and Lenses HQ. It exposes Lenses capabilities (topics, connectors, environments, SQL queries) as tools that your AI assistant can call.

### Authentication

The Lenses MCP Server supports two authentication methods:

#### OAuth 2.1 (Recommended) <a href="#oauth-21-recommended" id="oauth-21-recommended"></a>

OAuth 2.1 is the recommended approach for all deployments. It provides:

* **Secure token-based authentication** without sharing static API keys
* **Scope-based authorization** with read, write, and delete controls
* **Automatic token management** handled by your AI tool
* **Enterprise-grade security** suitable for production environments

When you connect your AI tool to the MCP Server, it automatically initiates the OAuth flow. You'll authenticate with your Lenses credentials and grant the scopes you need (read, write, delete). Your AI tool then uses this token for all subsequent requests.

#### API Key (Fallback) <a href="#api-key-fallback" id="api-key-fallback"></a>

For backward compatibility and local testing, you can use a static API key provisioned via a service account. This method is not recommended for production use.

### Capabilities

Through the MCP Server, your AI assistant can:

* **Explore Topics** — List, inspect, and query Kafka topics across your environments
* **Manage Connectors** — Create, update, monitor, and delete Kafka connectors
* **Execute SQL** — Run SQL queries against topics using Lenses SQL engine
* **Inspect Consumer Groups** — Monitor consumer lag and group status
* **Manage Environments** — Register and configure Kafka environments
* **Access Metadata** — Discover schemas, topic configurations, and cluster information

### Use Cases

* **Data Engineers:** Quickly explore Kafka topics, debug data pipelines, and validate connectors without leaving your IDE or AI assistant.
* **DataOps Teams:** Monitor connector health, manage consumer groups, and respond to incidents using natural language queries.
* **AI Engineers**: Build AI agents that can autonomously interact with your Kafka infrastructure for data discovery and management.

### Architecture

```
┌─────────────────┐
│   AI Tool       │
│  (Claude,       │
│   Cursor, etc)  │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────────────┐
│  Lenses MCP Server      │
│  • OAuth Validation     │
│  • Tool Execution       │
│  • Response Formatting  │
└────────┬────────────────┘
         │ HTTP/gRPC
         │
┌────────▼────────────────┐
│   Lenses HQ             │
│  • Authorization Server │
│  • API Gateway          │
└────────┬────────────────┘
         │
┌────────▼────────────────┐
│  Lenses Agents          │
│  • Kafka Brokers        │
│  • Schema Registries    │
│  • Kafka Connect        │
│  • Other Services       │
└─────────────────────────┘
```

### Security

The MCP Server is built with enterprise security in mind:

* **OAuth 2.1 Protected Resource** — Full RFC 7662 token introspection
* **PKCE Flow** — Proof Key for Code Exchange (S256) for client authorization
* **Token Validation** — Every request validates tokens before accessing Lenses APIs
* **Scope Enforcement** — Operations are limited by granted OAuth scopes
* **No Client Secrets** — The MCP server doesn't require credentials for token introspection

See the [Security](https://docs.lenses.io/latest/user-guide/using/security/oauth-2.1-for-mcp) section for details on OAuth configuration.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lenses.io/latest/user-guide/using/mcp-server.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.