🌊🔍 Servidor MCP de Lenses para Apache Kafka 🔎🌊

Este es el servidor MCP (Model Context Protocol) de Lenses para Apache Kafka. Lenses ofrece una solución de experiencia de desarrollo para ingenieros que crean aplicaciones en tiempo real conectadas a Kafka. Está diseñado para la empresa y respaldado por un potente modelo de IAM y gobernanza.

Con Lenses, puede encontrar, explorar, transformar, integrar y replicar datos a través de un entorno de múltiples Kafka y proveedores. Ahora, todo este poder es accesible a través de su asistente de IA o agente mediante este servidor MCP de Lenses para Kafka.

Véalo explicado y en acción mientras pasea por las calles de la ciudad de Nueva York.

Pruébelo hoy mismo con la Lenses Community Edition gratuita (restringida por número de usuarios y características empresariales). Lenses CE viene con un clúster de Kafka de un solo broker preconfigurado, ideal para desarrollo local o demostración. Conecte hasta dos de sus propios clústeres de Kafka y luego utilice lenguaje natural para interactuar con sus datos en streaming.

Tabla de contenidos

• 1. Instalar uv y Python

• 2. Configurar variables de entorno

• 3. Añadir clave de API de Lenses

• 4. Instalar dependencias y ejecutar el servidor

• 5. Servidor MCP opcional Context7

• 6. Ejecución con Docker

• 7. Autenticación OAuth 2.1

1. Instalar uv y Python

Utilizamos uv para la gestión de dependencias y la configuración del proyecto. Si no tiene uv instalado, siga la guía de instalación oficial.

Este proyecto ha sido construido utilizando Python 3.12 y para asegurarse de que Python esté instalado correctamente, ejecute el siguiente comando para comprobar la versión.

uv run python --version

2. Configurar variables de entorno

Copie el archivo de entorno de ejemplo.

cp .env.example .env

Abra .env y rellene los valores requeridos, como los detalles de su instancia de Lenses y la clave de API de Lenses.

3. Añadir clave de API de Lenses

Cree una clave de API de Lenses creando una cuenta de servicio IAM. Añada la clave de API a .env con el nombre de variable LENSES_API_KEY.

4. Instalar dependencias y ejecutar el servidor

Utilice uv para crear un entorno virtual, instale las dependencias del proyecto en él y luego ejecute el servidor MCP con la CLI de FastMCP utilizando el transporte stdio predeterminado.

uv sync
uv run src/lenses_mcp/server.py

Para ejecutarlo como un servidor remoto, utilice el transporte http.

uv run fastmcp run src/lenses_mcp/server.py --transport=http --port=8000

Para ejecutarlo en Claude Desktop, Gemini CLI, Cursor, etc., utilice la siguiente configuración JSON.

{
  "mcpServers": {
    "Lenses.io": {
      "command": "uv",
      "args": [
        "run",
        "--project", "<ABSOLUTE_PATH_TO_THIS_REPO>",
        "--with", "fastmcp",
        "fastmcp",
        "run",
        "<ABSOLUTE_PATH_TO_THIS_REPO>/src/lenses_mcp/server.py"
      ],
      "env": {
        "LENSES_API_KEY": "<YOUR_LENSES_API_KEY>"
      },
      "transport": "stdio"
    }
  }
}

Nota: Algunos clientes pueden requerir la ruta absoluta a uv en el comando.

5. Servidor MCP opcional Context7

La documentación de Lenses está disponible en Context7. Es opcional pero muy recomendable utilizar el servidor MCP de Context7 y ajustar sus prompts con use context7 para asegurar que la documentación disponible para el LLM esté actualizada.

6. Ejecución con Docker

El servidor MCP de Lenses está disponible como una imagen de Docker en lensesio/mcp. Puede ejecutarlo con diferentes modos de transporte dependiendo de su caso de uso.

Inicio rápido

Ejecute el servidor con transporte stdio (predeterminado):

docker run \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   lensesio/mcp

Ejecute el servidor con transporte HTTP (escucha en http://0.0.0.0:8000/mcp):

docker run -p 8000:8000 \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   -e TRANSPORT=http \
   lensesio/mcp

Ejecute el servidor con transporte SSE (escucha en http://0.0.0.0:8000/sse):

docker run -p 8000:8000 \
   -e LENSES_API_KEY=<YOUR_API_KEY> \
   -e LENSES_URL=http://localhost:9991 \
   -e TRANSPORT=sse \
   lensesio/mcp

Variables de entorno

Variables de entorno heredadas (para compatibilidad con versiones anteriores):

• LENSES_API_HTTP_URL, LENSES_API_HTTP_PORT

• LENSES_API_WEBSOCKET_URL, LENSES_API_WEBSOCKET_PORT

Estas se derivan automáticamente de LENSES_URL pero pueden establecerse explícitamente para sobrescribirlas.

Endpoints de transporte

• stdio: Entrada/salida estándar (sin endpoint de red)

• http: Endpoint HTTP en /mcp

• sse: Endpoint de eventos enviados por el servidor (Server-Sent Events) en /sse

Construcción de la imagen Docker

Para construir la imagen Docker localmente:

docker build -t lensesio/mcp .

7. Autenticación OAuth 2.1

Cuando se configura MCP_ADVERTISED_URL, el servidor MCP se ejecuta como un Recurso Protegido OAuth 2.1 con Introspección de Tokens RFC 7662 completa. Esto reemplaza el enfoque estático de LENSES_API_KEY con autenticación mediante token de portador (bearer token) para transportes HTTP, y también establece TRANSPORT a http por defecto.

Cómo funciona

El flujo de autenticación involucra a tres participantes: el cliente MCP, el servidor de autorización (Lenses HQ en LENSES_ADVERTISED_URL, que por defecto es LENSES_URL), y este servidor MCP (el servidor de recursos).

MCP Client                    Auth Server                   MCP Server
    │                              │                             │
    │  1. GET /.well-known/        │                             │
    │     oauth-protected-resource │                             │
    │─────────────────────────────────────────────────────────►  │
    │  ◄── authorization_servers,                                │
    │      scopes_supported                                      │
    │                              │                             │
    │  2. POST /register (DCR)     │                             │
    │─────────────────────────────►│                             │
    │  ◄── client_id, secret       │                             │
    │                              │                             │
    │  3. /authorize + PKCE (S256) │                             │
    │─────────────────────────────►│                             │
    │  ◄── authorization_code      │                             │
    │                              │                             │
    │  4. POST /token              │                             │
    │─────────────────────────────►│                             │
    │  ◄── access_token            │                             │
    │                              │                             │
    │  5. MCP request + Bearer token                             │
    │─────────────────────────────────────────────────────────►  │
    │                              │  6. POST /oauth2/introspect │
    │                              │  ◄──────────────────────────│
    │                              │  ── active, scopes, exp ──► │
    │                              │                             │
    │  ◄── MCP response (or 401)                                 │
    │                              │                             │

Los pasos 1–4 son manejados por el cliente MCP y el servidor de autorización. El servidor MCP no está involucrado.

Los pasos 5–6 son donde este servidor valida el token:

1. Metadatos de Recurso Protegido (RFC 9728) — RemoteAuthProvider sirve /.well-known/oauth-protected-resource/mcp para que los clientes puedan descubrir qué servidor de autorización usar y qué alcances están disponibles.

2. Auto-descubrimiento — En la primera solicitud entrante, el DiscoveryTokenVerifier obtiene de forma perezosa {LENSES_ADVERTISED_URL}/.well-known/oauth-authorization-server para descubrir el introspection_endpoint. La URL del endpoint también se puede establecer explícitamente a través de INTROSPECTION_URL.

3. Introspección de Token (RFC 7662) — Para cada token de portador entrante, el verificador hace un POST al endpoint de introspección (/oauth2/introspect) sin autenticación de cliente. El servidor de autorización responde con:

   • active — si el token es válido

   • scope — alcances concedidos (ej. read write)

   • client_id — el propietario del token

   • exp — marca de tiempo de expiración

   Los tokens inactivos o expirados son rechazados antes de llegar a la API de Lenses.

4. Reenvío de Token — Los tokens válidos se reenvían a la API de Lenses a través de Authorization: Bearer <token> para que Lenses pueda realizar sus propias comprobaciones de autorización.

Alcances de autorización

El servidor anuncia tres alcances en sus metadatos de recurso protegido:

Los alcances no se aplican globalmente a nivel de introspección: se acepta un token con cualquier subconjunto de estos alcances. La aplicación de alcances por herramienta se puede añadir utilizando el decorador require_scopes de FastMCP.

Configuración

En un despliegue simple, solo se requieren dos variables de entorno:

LENSES_URL=https://lenses.example.com
MCP_ADVERTISED_URL=http://localhost:8000

TRANSPORT se establece por defecto en http siempre que MCP_ADVERTISED_URL esté configurado, por lo que no necesita establecerlo explícitamente. LENSES_ADVERTISED_URL se establece por defecto en LENSES_URL, por lo que solo necesita establecerlo en despliegues de plano dividido donde el servidor MCP llega a Lenses en una dirección interna pero los clientes llegan a él en una pública:

# Split-plane: MCP server → Lenses over internal DNS,
# MCP clients → Lenses over the public URL
LENSES_URL=http://lenses-hq.internal:9991
LENSES_ADVERTISED_URL=https://lenses.example.com
MCP_ADVERTISED_URL=https://mcp.example.com

Lenses HQ (al que se llega a través de LENSES_ADVERTISED_URL) debe soportar:

• Metadatos del Servidor de Autorización OAuth 2.0 (RFC 8414) en /.well-known/oauth-authorization-server

• Introspección de Token (RFC 7662) en el introspection_endpoint, con la autenticación de cliente deshabilitada

• PKCE con S256 (RFC 7636) para flujos de autorización de cliente

El servidor MCP no envía credenciales de cliente al introspeccionar un token. En el lado de Lenses HQ esto requiere:

oauth2:
  authorizationServer:
    unauthenticatedIntrospection: true

en la configuración de Lenses HQ. Sin esta bandera, el endpoint de introspección rechazará el POST no autenticado del servidor MCP y cada token de portador será rechazado como inválido.

Ejecución con OAuth

# Local development
LENSES_URL=https://lenses.example.com \
MCP_ADVERTISED_URL=http://localhost:8000 \
uv run src/lenses_mcp/server.py

# Docker
docker run -p 8000:8000 \
   -e LENSES_URL=https://lenses.example.com \
   -e MCP_ADVERTISED_URL=http://localhost:8000 \
   lensesio/mcp

Cuando MCP_ADVERTISED_URL no está configurado, el servidor vuelve a la LENSES_API_KEY estática para compatibilidad con versiones anteriores y TRANSPORT se establece por defecto en stdio.