StreamNative MCP Server

Integrar agentes de IA con recursos de StreamNative Cloud y sistemas de mensajería Apache Kafka/Pulsar.

GitHub
24
Prueba este MCPPatrocinado

Documentación

StreamNative MCP Server

Un servidor de Protocolo de Contexto de Modelo (MCP) para integrar agentes de IA con recursos de StreamNative Cloud y sistemas de mensajería Apache Kafka/Pulsar.

Descripción General

StreamNative MCP Server proporciona una interfaz estándar para que LLMs (Modelos de Lenguaje de Gran Tamaño) y agentes de IA interactúen con los servicios de StreamNative Cloud, Apache Kafka y Apache Pulsar. Esta implementación sigue la especificación del Protocolo de Contexto de Modelo, permitiendo que las aplicaciones de IA accedan a servicios de mensajería a través de una interfaz estandarizada.

El servidor actualmente negocia las versiones de protocolo MCP 2025-11-25, 2025-06-18, 2025-03-26 y 2024-11-05. La preferencia predeterminada es 2025-11-25, mientras que los clientes más antiguos siguen siendo compatibles mediante la negociación de protocolo.

Características

  • Integración con StreamNative Cloud:
    • Conéctese a los recursos de StreamNative Cloud con autenticación
    • Cambie a los clústeres disponibles en su organización
    • Describa el estado de los recursos de los clústeres
  • Soporte para Apache Kafka: Interactúe con los recursos de Apache Kafka, incluyendo:
    • Operaciones de administración de Kafka (temas, particiones, grupos de consumidores)
    • Operaciones de Registro de Esquemas
    • Operaciones de Kafka Connect (*)
    • Operaciones de cliente de Kafka (productores, consumidores)
  • Soporte para Apache Pulsar: Interactúe con los recursos de Apache Pulsar, incluyendo:
    • Operaciones de administración de Pulsar (temas, espacios de nombres, inquilinos, esquemas, etc.)
    • Operaciones de cliente de Pulsar (productores, consumidores)
    • Gestión de Funciones, Fuentes y Sumideros
    • Recursos MCP de solo lectura para contexto, catálogo y resúmenes administrativos limitados
  • Múltiples Opciones de Conexión:
    • Conéctese a StreamNative Cloud con autenticación de cuenta de servicio
    • Conéctese directamente a clústeres externos de Apache Kafka
    • Conéctese directamente a clústeres externos de Apache Pulsar

*: Las operaciones de Kafka Connect solo se prueban y verifican en StreamNative Cloud.

Instalación

Homebrew (macOS y Linux)

La forma más sencilla de instalar streamnative-mcp-server es usando Homebrew:

# Add the tap repository
brew tap streamnative/streamnative

# Install streamnative-mcp-server
brew install streamnative/streamnative/snmcp

Imagen Docker

StreamNative MCP Server publica la Imagen Docker en streamnative/snmcp, y se puede usar para ejecutar tanto el servidor stdio como el servidor sse mediante el comando docker.

# Pull image from Docker Hub
docker pull streamnative/snmcp

Gráfico Helm (Kubernetes)

Consulte charts/snmcp/README.md para la instalación mediante Helm a través del repositorio de gráficos de StreamNative.

Desde la Publicación de GitHub

Visite https://github.com/streamnative/streamnative-mcp-server/releases para obtener el binario más reciente de StreamNative MCP Server.

Desde el Código Fuente

# Clone the repository
git clone https://github.com/streamnative/streamnative-mcp-server.git
cd streamnative-mcp-server

go mod tidy
go mod download

# Build the binary
make

Uso

Requisitos Previos

Si desea acceder a su StreamNative Cloud, necesitará tener los siguientes recursos listos:

  1. Acceso a StreamNative Cloud.
  2. Organización de StreamNative Cloud
  3. Instancia y clúster de StreamNative Cloud
  4. Cuenta de servicio con rol de administrador
  5. Descargue el archivo de clave de la cuenta de servicio

Iniciar el Servidor MCP

Usando el Servidor stdio

# Start MCP server with StreamNative Cloud authentication
bin/snmcp stdio --organization my-org --key-file /path/to/key-file.json

# Start MCP server with StreamNative Cloud authentication and pre-configured context
# When --pulsar-instance and --pulsar-cluster are provided, context mutation tools are disabled
bin/snmcp stdio --organization my-org --key-file /path/to/key-file.json --pulsar-instance my-instance --pulsar-cluster my-cluster

# Start MCP server with external Kafka
bin/snmcp stdio --use-external-kafka --kafka-bootstrap-servers localhost:9092 --kafka-auth-type SASL_SSL --kafka-auth-mechanism PLAIN --kafka-auth-user user --kafka-auth-pass pass --kafka-use-tls --kafka-schema-registry-url https://sr.local --kafka-schema-registry-auth-user user --kafka-schema-registry-auth-pass pass

# Start MCP server with external Pulsar
bin/snmcp stdio --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080
bin/snmcp stdio --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080 --pulsar-token "xxx"

# Start MCP server with stdio by docker with StreamNative Cloud authentication
docker run -i --rm -e SNMCP_ORGANIZATION=my-org -e SNMCP_KEY_FILE=/key.json -v /path/to/key-file.json:/key.json -p 9090:9090 streamnative/snmcp stdio

Usando el Servidor SSE (Eventos Enviados por el Servidor)

# Start MCP server with SSE and StreamNative Cloud authentication
bin/snmcp sse --http-addr :9090 --http-path /mcp --organization my-org --key-file /path/to/key-file.json

# Start MCP server with SSE and pre-configured StreamNative Cloud context
# When --pulsar-instance and --pulsar-cluster are provided, context mutation tools are disabled
bin/snmcp sse --http-addr :9090 --http-path /mcp --organization my-org --key-file /path/to/key-file.json --pulsar-instance my-instance --pulsar-cluster my-cluster

# Start MCP server with SSE and external Kafka
bin/snmcp sse --http-addr :9090 --http-path /mcp --use-external-kafka --kafka-bootstrap-servers localhost:9092

# Start MCP server with SSE and external Pulsar
bin/snmcp sse --http-addr :9090 --http-path /mcp --use-external-pulsar --pulsar-web-service-url http://pulsar.example.com:8080

# Start MCP server with SSE by docker with StreamNative Cloud authentication
docker run -i --rm -e SNMCP_ORGANIZATION=my-org -e SNMCP_KEY_FILE=/key.json -v /path/to/key-file.json:/key.json -p 9090:9090 streamnative/snmcp sse

Modo Pulsar Multisesión (solo SSE)

Cuando ejecuta el servidor SSE con Pulsar externo, puede habilitar el modo multisesión para admitir autenticación por usuario. En este modo, cada solicitud HTTP debe incluir un encabezado Authorization: Bearer <token>, y el servidor creará sesiones Pulsar separadas para cada token único.

# Start SSE server with multi-session Pulsar mode
bin/snmcp sse --http-addr :9090 --http-path /mcp \
  --use-external-pulsar \
  --pulsar-web-service-url http://pulsar.example.com:8080 \
  --multi-session-pulsar \
  --session-cache-size 100 \
  --session-ttl-minutes 30

Características clave:

  • Sesiones por usuario: El token Pulsar de cada usuario crea una sesión separada
  • Almacenamiento en caché LRU: Las sesiones se almacenan en caché con expulsión LRU cuando la caché está llena
  • Limpieza basada en TTL: Las sesiones inactivas se limpian automáticamente después del TTL configurado
  • Autenticación estricta: Las solicitudes sin un encabezado Authorization válido reciben HTTP 401 No Autorizado

Flujo de autenticación:

  1. El cliente se conecta al punto final SSE con el encabezado Authorization: Bearer <pulsar-jwt-token>
  2. El servidor valida el token intentando crear una sesión Pulsar
  3. Si es válido, la sesión se almacena en caché y se reutiliza para solicitudes posteriores
  4. Si es inválido o falta, el servidor devuelve HTTP 401 No Autorizado

Opciones de configuración:

IndicadorPredeterminadoDescripción
--multi-session-pulsarfalseHabilitar sesiones Pulsar por usuario
--session-cache-size100Número máximo de sesiones almacenadas en caché
--session-ttl-minutes30Tiempo de espera de inactividad de la sesión antes de la expulsión

Nota: El modo multisesión solo está disponible para el modo Pulsar externo (--use-external-pulsar) y solo funciona con el servidor SSE, no con stdio.

Opciones de Línea de Comandos

Usage:
  bin/snmcp [command]

Available Commands:
  stdio       Start stdio server
  sse         Start sse server
  help        Help about any command

Flags:
      --audience string                        The audience identifier for the API server (default "https://api.streamnative.cloud")
      --client-id string                       The client ID to use for authorization grants (default "AJYEdHWi9EFekEaUXkPWA2MqQ3lq1NrI")
      --config-dir string                      If present, the config directory to use
      --enable-command-logging                 When enabled, the server will log all command requests and responses to the log file
      --features strings                       Features to enable, defaults to `all`
  -h, --help                                   help for bin/snmcp
      --issuer string                          The OAuth 2.0 issuer endpoint (default "https://auth.streamnative.cloud/")
      --kafka-auth-mechanism string            The auth mechanism to use for Kafka
      --kafka-auth-pass string                 The auth password to use for Kafka
      --kafka-auth-type string                 The auth type to use for Kafka
      --kafka-auth-user string                 The auth user to use for Kafka
      --kafka-bootstrap-servers string         The bootstrap servers to use for Kafka
      --kafka-ca-file string                   The CA file to use for Kafka
      --kafka-client-cert-file string          The client certificate file to use for Kafka
      --kafka-client-key-file string           The client key file to use for Kafka
      --kafka-schema-registry-auth-pass string The auth password to use for the schema registry
      --kafka-schema-registry-auth-user string The auth user to use for the schema registry
      --kafka-schema-registry-bearer-token string The bearer token to use for the schema registry
      --kafka-schema-registry-url string       The schema registry URL to use for Kafka
      --key-file string                        The key file to use for authentication to StreamNative Cloud
      --log-file string                        Path to log file
      --organization string                    The organization to use for the API server
      --proxy-location string                  The proxy location to use for the API server (default "https://proxy.streamnative.cloud")
      --pulsar-auth-params string              The auth params to use for Pulsar
      --pulsar-auth-plugin string              The auth plugin to use for Pulsar
      --pulsar-token string                    The token to use for Pulsar
      --pulsar-cluster string                  The default cluster to use for the API server
      --pulsar-instance string                 The default instance to use for the API server
      --pulsar-tls-allow-insecure-connection   The TLS allow insecure connection to use for Pulsar
      --pulsar-tls-cert-file string            The TLS cert file to use for Pulsar
      --pulsar-tls-enable-hostname-verification The TLS enable hostname verification to use for Pulsar (default true)
      --pulsar-tls-key-file string             The TLS key file to use for Pulsar
      --pulsar-tls-trust-certs-file-path string The TLS trust certs file path to use for Pulsar
      --pulsar-web-service-url string          The web service URL to use for Pulsar
  -r, --read-only                              Read-only mode
      --server string                          The server to connect to (default "https://api.streamnative.cloud")
      --use-external-kafka                     Use external Kafka
      --use-external-pulsar                    Use external Pulsar
      --http-addr string                       HTTP server address (default ":9090")
      --http-path string                       HTTP server path for SSE endpoint (default "/mcp")
      --multi-session-pulsar                   Enable per-user Pulsar sessions based on Authorization header tokens (only for external Pulsar mode)
      --session-cache-size int                 Maximum number of cached Pulsar sessions when multi-session is enabled (default 100)
      --session-ttl-minutes int                Session TTL in minutes before eviction when multi-session is enabled (default 30)
  -v, --version                                version for bin/snmcp

Configuración de Herramientas

StreamNative MCP Server admite habilitar o deshabilitar grupos específicos de funcionalidades mediante el indicador --features. Esto le permite controlar qué herramientas MCP están disponibles para sus herramientas de IA. Habilitar solo los conjuntos de herramientas que necesita puede ayudar al LLM con la elección de herramientas y reducir el tamaño del contexto.

Características Disponibles

StreamNative MCP Server le permite habilitar o deshabilitar grupos específicos de características usando el indicador --features. Esto le ayuda a controlar qué herramientas están disponibles para sus agentes de IA y puede reducir el tamaño del contexto para los LLMs.

Conjuntos de Características Combinados

CaracterísticaDescripción
allHabilita todas las características: herramientas de StreamNative Cloud, Pulsar y Kafka

Compatibilidad con el conector Claude: las herramientas de administración que anteriormente mezclaban operaciones de lectura y escritura detrás de un parámetro operation ahora se exponen como herramientas MCP de lectura/escritura separadas, por ejemplo kafka_admin_topics_read y kafka_admin_topics_write. Las herramientas de lectura incluyen annotations.readOnlyHint=true; las herramientas de escritura o con efectos secundarios incluyen annotations.destructiveHint=true. En el modo --read-only, las herramientas de escritura/destructivas no se registran.

Características de Kafka

CaracterísticaDescripciónDocumentación
all-kafkaHabilita todas las herramientas de administración y cliente de Kafka, sin las herramientas de Apache Pulsar y StreamNative Cloud
kafka-adminOperaciones administrativas de Kafka (todas las herramientas de administración)
kafka-clientOperaciones de cliente de Kafka (producir/consumir)kafka_client_consume.md, kafka_client_produce.md
kafka-admin-topicsGestionar temas de Kafkakafka_admin_topics.md
kafka-admin-partitionsGestionar particiones de Kafkakafka_admin_partitions.md
kafka-admin-groupsGestionar grupos de consumidores de Kafkakafka_admin_groups.md
kafka-admin-schema-registryInteractuar con el Registro de Esquemas de Kafkakafka_admin_schema_registry.md
kafka-admin-connectGestionar conectores de Kafka Connectkafka_admin_connect.md

Características de Pulsar

CaracterísticaDescripciónDocumentación
all-pulsarHabilita todas las herramientas de administración y cliente de Pulsar, sin las herramientas de Apache Kafka y StreamNative Cloudpulsar_resources.md
pulsar-adminOperaciones administrativas de Pulsar (todas las herramientas de administración)pulsar_resources.md
pulsar-clientOperaciones de cliente de Pulsar (producir/consumir)pulsar_client_consume.md, pulsar_client_produce.md
pulsar-admin-brokersGestionar brokers de Pulsarpulsar_admin_brokers.md
pulsar-admin-brokers-statusVerificar el estado del broker o proxy de Pulsarpulsar_admin_status.md
pulsar-admin-broker-statsAcceder a las estadísticas del broker de Pulsarpulsar_admin_broker_stats.md
pulsar-admin-clustersGestionar clústeres de Pulsarpulsar_admin_clusters.md
pulsar-admin-functions-workerGestionar los workers de funciones de Pulsarpulsar_admin_functions_worker.md
pulsar-admin-namespacesGestionar espacios de nombres de Pulsarpulsar_admin_namespaces.md
pulsar-admin-namespace-policyConfigurar políticas de espacios de nombres de Pulsarpulsar_admin_namespace_policy.md
pulsar-admin-ns-isolation-policyGestionar políticas de aislamiento de espacios de nombrespulsar_admin_nsisolationpolicy.md
pulsar-admin-packagesGestionar paquetes de Pulsarpulsar_admin_packages.md
pulsar-admin-resource-quotasConfigurar cuotas de recursospulsar_admin_resource_quotas.md
pulsar-admin-schemasGestionar esquemas de Pulsarpulsar_admin_schemas.md
pulsar-admin-subscriptionsGestionar suscripciones de Pulsarpulsar_admin_subscriptions.md
pulsar-admin-tenantsGestionar inquilinos de Pulsarpulsar_admin_tenants.md
pulsar-admin-topicsGestionar temas de Pulsarpulsar_admin_topics.md
pulsar-admin-sinksGestionar sumideros de IO de Pulsarpulsar_admin_sinks.md
pulsar-admin-functionsGestionar Funciones de Pulsarpulsar_admin_functions.md
pulsar-admin-sourcesGestionar Fuentes de Pulsarpulsar_admin_sources.md
pulsar-admin-topic-policyConfigurar políticas de temas de Pulsarpulsar_admin_topic_policy.md

Las puertas de características de administración de Pulsar también registran recursos MCP de solo lectura para la superficie administrativa correspondiente. Estos recursos usan URIs pulsar://..., devuelven instantáneas JSON y se mantienen separados de las herramientas con capacidad de escritura; consulte pulsar_resources.md para las plantillas de URI admitidas y los límites de seguridad.

Características de StreamNative Cloud

CaracterísticaDescripciónDocumentación
streamnative-cloudGestionar el contexto de StreamNative Cloud y verificar los registros de recursosstreamnative_cloud.md
functions-as-toolsExpone dinámicamente las Funciones de Pulsar implementadas como herramientas MCP invocables, con manejo automático de esquemas de entrada/salida.functions_as_tools.md

Nota: Cuando se usan los indicadores --pulsar-instance y --pulsar-cluster juntos, las herramientas de mutación de contexto (sncloud_context_use_cluster, sncloud_context_reset) se deshabilitan automáticamente ya que el contexto está preconfigurado.

Puede combinar estas características según sea necesario usando el indicador --features. Por ejemplo, para habilitar solo las características de cliente de Pulsar:

# Enable only Pulsar client features
bin/snmcp stdio --organization my-org --key-file /path/to/key-file.json --features pulsar-client

Inspeccionando el Servidor MCP

Puede usar la herramienta @modelcontextprotocol/inspector para inspeccionar y probar su servidor MCP. Esto es particularmente útil para depurar y verificar la configuración de su servidor.

Instalación

npm install -g @modelcontextprotocol/inspector

Uso

# Inspect a stdio server
mcp-inspector stdio --command "bin/snmcp stdio --organization my-org --key-file /path/to/key-file.json"

# Inspect an SSE server
mcp-inspector sse --url "http://localhost:9090/mcp"

El inspector proporciona una interfaz web donde puede:

  • Ver las herramientas disponibles y sus esquemas
  • Probar invocaciones de herramientas
  • Monitorear las respuestas del servidor
  • Depurar problemas de conexión

Integración con Clientes MCP

Este servidor se puede usar con cualquier cliente compatible con MCP, como:

  • Claude Desktop
  • Otros asistentes de IA que admitan el protocolo MCP
  • Aplicaciones personalizadas creadas con bibliotecas de cliente MCP

⚠️ Recordatorio: Asegúrate de tener un plan de pago activo con tu proveedor de LLM para utilizar completamente el servidor MCP. Sin él, es posible que encuentres el error: message will exceed the length limit for this chat.

Uso con Claude Desktop

Usando el servidor stdio

{
  "mcpServers": {
    "mcp-streamnative": {
      "command": "${PATH_TO_SNMCP}/bin/snmcp",
      "args": [
        "stdio",
        "--organization",
        "${STREAMNATIVE_CLOUD_ORGANIZATION_ID}",
        "--key-file",
        "${STREAMNATIVE_CLOUD_KEY_FILE}"
      ]
    }
  }
}

Recuerda reemplazar ${PATH_TO_SNMCP} con la ruta real al binario de snmcp y ${STREAMNATIVE_CLOUD_ORGANIZATION_ID} y ${STREAMNATIVE_CLOUD_KEY_FILE} con el ID de organización de StreamNative Cloud y la ruta del archivo de clave, respectivamente.

Opcionalmente, puedes usar la imagen de Docker para iniciar el servidor stdio si tienes Docker instalado.

{
  "mcpServers": {
    "mcp-streamnative": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "SNMCP_ORGANIZATION",
        "-e",
        "SNMCP_KEY_FILE",
        "-v",
        "${STREAMNATIVE_CLOUD_KEY_FILE}:/key.json",
        "streamnative/snmcp",
        "stdio"
      ],
      "env": {
        "SNMCP_ORGANIZATION": "${STREAMNATIVE_CLOUD_ORGANIZATION_ID}",
        "SNMCP_KEY_FILE": "/key.json"
      }
    }
  }
}

Usando el servidor SSE

Primero, instala la herramienta mcp-proxy:

pip install mcp-proxy

Luego configura Claude Desktop para usar el servidor SSE:

{
  "mcpServers": {
    "mcp-streamnative-proxy": {
      "command": "mcp-proxy",
      "args": [
        "http://localhost:9090/mcp/sse"
      ]
    }
  }
}

Nota: Si mcp-proxy no está en tu PATH del sistema, deberás proporcionar la ruta completa al ejecutable. Por ejemplo:

  • En macOS: /Library/Frameworks/Python.framework/Versions/3.11/bin/mcp-proxy
  • En Linux: /usr/local/bin/mcp-proxy
  • En Windows: C:\Python311\Scripts\mcp-proxy.exe

Recuerda reemplazar http://localhost:9090/mcp/sse con la URL correcta.

Acerca del Protocolo de Contexto de Modelo (MCP)

El Protocolo de Contexto de Modelo (MCP) es un protocolo abierto que estandariza cómo las aplicaciones proporcionan contexto a los LLM. MCP ayuda a construir agentes y flujos de trabajo complejos sobre LLM al proporcionar:

  • Una lista creciente de integraciones preconstruidas a las que tu LLM puede conectarse directamente
  • La flexibilidad para cambiar entre proveedores y vendedores de LLM
  • Mejores prácticas para asegurar tus datos dentro de tu infraestructura

Para más información, visita modelcontextprotocol.io.

Lanzamiento

Esta sección describe cómo lanzar una nueva versión de snmcp.

  1. Genera una etiqueta para la nueva versión (consulta Versionado, a continuación):
git tag -a v0.0.1 -m "v0.0.1"
  1. Envía la etiqueta al repositorio de git:
git push origin refs/tags/v0.0.1

El flujo de trabajo de lanzamiento:

  • compilará binarios de Go para las plataformas compatibles
  • archivará los binarios
  • publicará un lanzamiento en el repositorio de GitHub (ref)

Versionado

Este proyecto utiliza semántica semver.

  • Estable: vX.Y.Z
  • Pre-lanzamiento: vX.Y.Z-rc.W
  • Instantánea: vX.Y.Z-SNAPSHOT-commit

Licencia

Licenciado bajo la Licencia Apache Versión 2.0: http://www.apache.org/licenses/LICENSE-2.0