StreamNative MCP Server

Integre agentes de IA com recursos do StreamNative Cloud e sistemas de mensageria Apache Kafka/Pulsar.

GitHub
24
Experimente este MCPPatrocinado

Documentação

StreamNative MCP Server

Um servidor Model Context Protocol (MCP) para integrar agentes de IA com recursos do StreamNative Cloud e sistemas de mensageria Apache Kafka/Pulsar.

Visão Geral

O StreamNative MCP Server fornece uma interface padrão para LLMs (Large Language Models) e agentes de IA interagirem com os serviços do StreamNative Cloud, Apache Kafka e Apache Pulsar. Esta implementação segue a especificação do Model Context Protocol, permitindo que aplicações de IA acessem serviços de mensageria por meio de uma interface padronizada.

O servidor atualmente negocia as versões de protocolo MCP 2025-11-25, 2025-06-18, 2025-03-26 e 2024-11-05. A preferência padrão é 2025-11-25, enquanto clientes mais antigos permanecem suportados por meio da negociação de protocolo.

Recursos

  • Integração com StreamNative Cloud:
    • Conecte-se aos recursos do StreamNative Cloud com autenticação
    • Alterne para clusters disponíveis na sua organização
    • Descreva o status dos recursos dos clusters
  • Suporte a Apache Kafka: Interaja com recursos do Apache Kafka, incluindo:
    • Operações de administração do Kafka (tópicos, partições, grupos de consumidores)
    • Operações do Schema Registry
    • Operações do Kafka Connect (*)
    • Operações de cliente Kafka (produtores, consumidores)
  • Suporte a Apache Pulsar: Interaja com recursos do Apache Pulsar, incluindo:
    • Operações de administração do Pulsar (tópicos, namespaces, tenants, schemas, etc.)
    • Operações de cliente Pulsar (produtores, consumidores)
    • Gerenciamento de Functions, Sources e Sinks
    • Recursos MCP somente leitura para contexto, catálogo e resumos administrativos limitados
  • Múltiplas Opções de Conexão:
    • Conecte-se ao StreamNative Cloud com autenticação de service account
    • Conecte-se diretamente a clusters Apache Kafka externos
    • Conecte-se diretamente a clusters Apache Pulsar externos

*: As operações do Kafka Connect são testadas e verificadas apenas no StreamNative Cloud.

Instalação

Homebrew (macOS e Linux)

A maneira mais fácil de instalar o streamnative-mcp-server é usando o Homebrew:

# Add the tap repository
brew tap streamnative/streamnative

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

Imagem Docker

O StreamNative MCP Server publica a Imagem Docker em streamnative/snmcp, e ela pode ser usada para executar tanto o servidor stdio quanto o servidor sse por meio do comando docker.

# Pull image from Docker Hub
docker pull streamnative/snmcp

Helm Chart (Kubernetes)

Consulte charts/snmcp/README.md para instalação via Helm usando o repositório de charts do StreamNative.

A partir do Github Release

Visite https://github.com/streamnative/streamnative-mcp-server/releases para obter o binário mais recente do StreamNative MCP Server.

A partir do Código Fonte

# 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

Pré-requisitos

Se você deseja acessar seu StreamNative Cloud, precisará ter os seguintes recursos prontos:

  1. Acesso ao StreamNative Cloud.
  2. Organização no StreamNative Cloud
  3. Instância e cluster no StreamNative Cloud
  4. Service Account com função de administrador
  5. Baixar o arquivo de chave do Service Account

Iniciar o MCP Server

Usando o 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 o Servidor SSE (Server-Sent Events)

# 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 Multi-Sessão Pulsar (somente SSE)

Ao executar o servidor SSE com Pulsar externo, você pode habilitar o modo multi-sessão para suportar autenticação por usuário. Neste modo, cada requisição HTTP deve incluir um cabeçalho Authorization: Bearer <token>, e o servidor criará sessões 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

Principais recursos:

  • Sessões por usuário: O token Pulsar de cada usuário cria uma sessão separada
  • Cache LRU: As sessões são armazenadas em cache com remoção LRU quando o cache está cheio
  • Limpeza baseada em TTL: Sessões ociosas são limpas automaticamente após o TTL configurado
  • Autenticação estrita: Requisições sem um cabeçalho Authorization válido recebem HTTP 401 Não Autorizado

Fluxo de autenticação:

  1. O cliente conecta-se ao endpoint SSE com o cabeçalho Authorization: Bearer <pulsar-jwt-token>
  2. O servidor valida o token tentando criar uma sessão Pulsar
  3. Se válido, a sessão é armazenada em cache e reutilizada para requisições subsequentes
  4. Se inválido ou ausente, o servidor retorna HTTP 401 Não Autorizado

Opções de configuração:

FlagPadrãoDescrição
--multi-session-pulsarfalseHabilita sessões Pulsar por usuário
--session-cache-size100Número máximo de sessões em cache
--session-ttl-minutes30Tempo limite de inatividade da sessão antes da remoção

Nota: O modo multi-sessão está disponível apenas para o modo Pulsar externo (--use-external-pulsar) e funciona somente com o servidor SSE, não com stdio.

Opções de Linha de Comando

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

Configuração de Ferramentas

O StreamNative MCP Server suporta habilitar ou desabilitar grupos específicos de funcionalidades por meio da flag --features. Isso permite que você controle quais ferramentas MCP estão disponíveis para suas ferramentas de IA. Habilitar apenas os conjuntos de ferramentas que você precisa pode ajudar o LLM na escolha de ferramentas e reduzir o tamanho do contexto.

Recursos Disponíveis

O StreamNative MCP Server permite que você habilite ou desabilite grupos específicos de recursos usando a flag --features. Isso ajuda a controlar quais ferramentas estão disponíveis para seus agentes de IA e pode reduzir o tamanho do contexto para LLMs.

Conjuntos de Recursos Combinados

RecursoDescrição
allHabilita todos os recursos: ferramentas do StreamNative Cloud, Pulsar e Kafka

Compatibilidade com conectores Claude: ferramentas administrativas que anteriormente misturavam operações de leitura e escrita em um único parâmetro operation agora são expostas como ferramentas MCP separadas de leitura/escrita, por exemplo kafka_admin_topics_read e kafka_admin_topics_write. Ferramentas de leitura incluem annotations.readOnlyHint=true; ferramentas de escrita ou com efeitos colaterais incluem annotations.destructiveHint=true. No modo --read-only, ferramentas de escrita/destrutivas não são registradas.

Recursos Kafka

RecursoDescriçãoDocs
all-kafkaHabilita todas as ferramentas de administração e cliente Kafka, sem as ferramentas do Apache Pulsar e StreamNative Cloud
kafka-adminOperações administrativas do Kafka (todas as ferramentas de administração)
kafka-clientOperações de cliente Kafka (produzir/consumir)kafka_client_consume.md, kafka_client_produce.md
kafka-admin-topicsGerenciar tópicos Kafkakafka_admin_topics.md
kafka-admin-partitionsGerenciar partições Kafkakafka_admin_partitions.md
kafka-admin-groupsGerenciar grupos de consumidores Kafkakafka_admin_groups.md
kafka-admin-schema-registryInteragir com o Schema Registry do Kafkakafka_admin_schema_registry.md
kafka-admin-connectGerenciar conectores Kafka Connectkafka_admin_connect.md

Recursos Pulsar

RecursoDescriçãoDocs
all-pulsarHabilita todas as ferramentas de administração e cliente Pulsar, sem as ferramentas do Apache Kafka e StreamNative Cloudpulsar_resources.md
pulsar-adminOperações administrativas do Pulsar (todas as ferramentas de administração)pulsar_resources.md
pulsar-clientOperações de cliente Pulsar (produzir/consumir)pulsar_client_consume.md, pulsar_client_produce.md
pulsar-admin-brokersGerenciar brokers Pulsarpulsar_admin_brokers.md
pulsar-admin-brokers-statusVerificar o status do broker ou proxy Pulsarpulsar_admin_status.md
pulsar-admin-broker-statsAcessar estatísticas dos brokers Pulsarpulsar_admin_broker_stats.md
pulsar-admin-clustersGerenciar clusters Pulsarpulsar_admin_clusters.md
pulsar-admin-functions-workerGerenciar workers de Functions Pulsarpulsar_admin_functions_worker.md
pulsar-admin-namespacesGerenciar namespaces Pulsarpulsar_admin_namespaces.md
pulsar-admin-namespace-policyConfigurar políticas de namespaces Pulsarpulsar_admin_namespace_policy.md
pulsar-admin-ns-isolation-policyGerenciar políticas de isolamento de namespacespulsar_admin_nsisolationpolicy.md
pulsar-admin-packagesGerenciar pacotes Pulsarpulsar_admin_packages.md
pulsar-admin-resource-quotasConfigurar cotas de recursospulsar_admin_resource_quotas.md
pulsar-admin-schemasGerenciar schemas Pulsarpulsar_admin_schemas.md
pulsar-admin-subscriptionsGerenciar assinaturas Pulsarpulsar_admin_subscriptions.md
pulsar-admin-tenantsGerenciar tenants Pulsarpulsar_admin_tenants.md
pulsar-admin-topicsGerenciar tópicos Pulsarpulsar_admin_topics.md
pulsar-admin-sinksGerenciar sinks de IO do Pulsarpulsar_admin_sinks.md
pulsar-admin-functionsGerenciar Functions Pulsarpulsar_admin_functions.md
pulsar-admin-sourcesGerenciar Sources Pulsarpulsar_admin_sources.md
pulsar-admin-topic-policyConfigurar políticas de tópicos Pulsarpulsar_admin_topic_policy.md

Os portões de recursos administrativos do Pulsar também registram recursos MCP somente leitura para a superfície administrativa correspondente. Esses recursos usam URIs pulsar://..., retornam snapshots JSON e permanecem separados das ferramentas com capacidade de escrita; consulte pulsar_resources.md para os modelos de URI suportados e limites de segurança.

Recursos do StreamNative Cloud

RecursoDescriçãoDocs
streamnative-cloudGerenciar o contexto do StreamNative Cloud e verificar logs de recursosstreamnative_cloud.md
functions-as-toolsExpõe dinamicamente Functions Pulsar implantadas como ferramentas MCP invocáveis, com tratamento automático de schema de entrada/saída.functions_as_tools.md

Nota: Ao usar as flags --pulsar-instance e --pulsar-cluster juntas, as ferramentas de mutação de contexto (sncloud_context_use_cluster, sncloud_context_reset) são desabilitadas automaticamente, pois o contexto é pré-configurado.

Você pode combinar esses recursos conforme necessário usando a flag --features. Por exemplo, para habilitar apenas os recursos de cliente Pulsar:

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

Inspecionando o MCP Server

Você pode usar a ferramenta @modelcontextprotocol/inspector para inspecionar e testar seu MCP server. Isso é particularmente útil para depuração e verificação da configuração do seu servidor.

Instalação

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"

O inspector fornece uma interface web onde você pode:

  • Visualizar as ferramentas disponíveis e seus schemas
  • Testar invocações de ferramentas
  • Monitorar respostas do servidor
  • Depurar problemas de conexão

Integração com Clientes MCP

Este servidor pode ser usado com qualquer cliente compatível com MCP, como:

  • Claude Desktop
  • Outros assistentes de IA que suportam o protocolo MCP
  • Aplicações personalizadas construídas com bibliotecas de cliente MCP

⚠️ Lembrete: Certifique-se de ter um plano pago ativo com seu provedor de LLM para utilizar totalmente o servidor MCP. Sem ele, você pode encontrar o erro: message will exceed the length limit for this chat.

Uso com Claude Desktop

Usando o servidor stdio

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

Lembre-se de substituir ${PATH_TO_SNMCP} pelo caminho real para o binário snmcp e ${STREAMNATIVE_CLOUD_ORGANIZATION_ID} e ${STREAMNATIVE_CLOUD_KEY_FILE} pelo ID da organização do StreamNative Cloud e o caminho do arquivo de chave, respectivamente.

Opcionalmente, você pode usar a imagem docker para iniciar o servidor stdio se tiver o 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 o servidor SSE

Primeiro, instale a ferramenta mcp-proxy:

pip install mcp-proxy

Em seguida, configure o Claude Desktop para usar o servidor SSE:

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

Nota: Se o mcp-proxy não estiver no PATH do seu sistema, você precisará fornecer o caminho completo para o executável. Por exemplo:

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

Lembre-se de substituir http://localhost:9090/mcp/sse pela URL correta.

Sobre o Model Context Protocol (MCP)

O Model Context Protocol (MCP) é um protocolo aberto que padroniza como aplicações fornecem contexto para LLMs. O MCP ajuda a construir agentes e fluxos de trabalho complexos sobre LLMs, fornecendo:

  • Uma lista crescente de integrações pré-construídas nas quais seu LLM pode se conectar diretamente
  • A flexibilidade para alternar entre provedores e fornecedores de LLM
  • Melhores práticas para proteger seus dados dentro da sua infraestrutura

Para mais informações, visite modelcontextprotocol.io.

Lançamento

Esta seção descreve como lançar uma nova versão do snmcp.

  1. Gere uma tag para a nova versão (veja Versionamento, abaixo):
git tag -a v0.0.1 -m "v0.0.1"
  1. Envie a tag para o repositório git:
git push origin refs/tags/v0.0.1

O fluxo de trabalho de lançamento irá:

  • compilar binários Go para plataformas suportadas
  • arquivar os binários
  • publicar um lançamento no repositório github (ref)

Versionamento

Este projeto usa semântica semver.

  • Estável: vX.Y.Z
  • Pré-lançamento: vX.Y.Z-rc.W
  • Snapshot: vX.Y.Z-SNAPSHOT-commit

Licença

Licenciado sob a Apache License Versão 2.0: http://www.apache.org/licenses/LICENSE-2.0