Aiven

oficial

Navegue pelos seus projetos Aiven e interaja com os serviços PostgreSQL®, Apache Kafka®, ClickHouse® e OpenSearch®

GitHub

O que você pode fazer com Aiven MCP?

Listar e inspecionar projetos Aiven — Use aiven_project_list e aiven_project_get para navegar pelos projetos e visualizar seus detalhes.
Gerenciar serviços Aiven — Crie, atualize ou recupere serviços com aiven_service_create, aiven_service_update e aiven_service_get.
Trabalhar com tópicos e conectores Kafka — Liste, crie, atualize, exclua tópicos, produza/consuma mensagens e gerencie conectores Kafka Connect.
Executar SQL em serviços PostgreSQL — Execute consultas somente leitura com aiven_pg_read ou instruções de escrita com aiven_pg_write.
Implantar e reimplantar aplicações — Use aiven_application_deploy e aiven_application_redeploy para gerenciar aplicações Dockerizadas no Aiven.
Pesquisar documentação do Aiven — Consulte a documentação oficial em linguagem natural através de aiven_docs_search (apenas servidor hospedado).

Documentação

Servidor MCP Aiven

Um servidor Model Context Protocol (MCP) para a plataforma de dados em nuvem Aiven.

Gerencie PostgreSQL, Apache Kafka, aplicações e outros serviços Aiven diretamente de assistentes de IA como Claude, Cursor e VS Code Copilot.

[!WARNING] Use com cuidado. Este servidor MCP pode criar, modificar e excluir serviços e dados Aiven em seu nome. Agentes de IA podem executar ações destrutivas (excluir bancos de dados, remover serviços, produzir mensagens) com base na interpretação de seus prompts. Você é totalmente responsável pelas ações realizadas por meio desta ferramenta.

Permissões: O acesso é regido pelas permissões de usuário Aiven associadas à conta autenticada. O servidor MCP só pode executar ações que seu usuário Aiven tem permissão para fazer.

Segurança do Agente de IA: Agentes de IA podem precisar de credenciais de acesso (strings de conexão de banco de dados, tokens de streaming) para agir em seu nome. Revise o que seu agente está fazendo, especialmente em ambientes de produção. Siga as políticas de segurança da sua organização e faça uma avaliação de risco antes de dar a agentes de IA acesso a recursos sensíveis.

Início Rápido

Opção 1: Remoto (hospedado pela Aiven)

O servidor MCP está hospedado em https://mcp.aiven.live/mcp. Seu cliente MCP solicitará que você autorize na Aiven.

Claude Code

claude mcp add --scope user --transport http aiven-mcp "https://mcp.aiven.live/mcp"

Cursor

Ou adicione manualmente às configurações MCP do Cursor:

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp"
    }
  }
}

VS Code / Copilot

Adicione ao .vscode/mcp.json no seu workspace:

{
  "servers": {
    "aiven-mcp": {
      "type": "http",
      "url": "https://mcp.aiven.live/mcp"
    }
  }
}

Modo Somente Leitura (Remoto)

Habilite o modo somente leitura adicionando ?read_only=true à URL. Todas as operações de escrita serão excluídas do MCP:

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp?read_only=true"
    }
  }
}

Ferramentas com Escopo (Remoto)

Reduza a superfície de ferramentas exposta ao seu agente de IA adicionando ?services_scope= à URL. Útil quando você trabalha apenas com um subconjunto de serviços Aiven e deseja manter o contexto do agente focado. Combine valores com vírgulas. core (descoberta de projeto/serviço) está sempre incluído implicitamente.

Escopos válidos: all, core, pg, kafka, application, integrations. Use all para carregar explicitamente todas as ferramentas (o mesmo que omitir o parâmetro). all não pode ser combinado com outros escopos.

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp?services_scope=kafka"
    }
  }
}

Você também pode combinar com read_only:

https://mcp.aiven.live/mcp?services_scope=pg&read_only=true

Exceções de Escrita no Modo Somente Leitura (Remoto)

Quando read_only=true, adicione ?write_allowlist= para reabilitar ferramentas de escrita específicas enquanto mantém todo o resto como somente leitura. Útil quando você deseja acesso majoritariamente de leitura, mas ainda precisa permitir uma ação de escrita, por exemplo, criar tópicos Kafka. Combine vários nomes de ferramentas com vírgulas. Ignorado quando read_only não está habilitado.

https://mcp.aiven.live/mcp?read_only=true&write_allowlist=aiven_kafka_topic_create

Clientes do Marketplace (Remoto)

Se você assinou a Aiven através de um marketplace de nuvem, adicione seu marketplace como um segmento de caminho para que o login use o console correto:

Marketplace	Segmento de caminho
AWS Marketplace	`https://mcp.aiven.live/mcp/aws`
Azure Marketplace	`https://mcp.aiven.live/mcp/azure`
Google Cloud Marketplace	`https://mcp.aiven.live/mcp/gcp`

{
  "mcpServers": {
    "aiven-mcp": {
      "url": "https://mcp.aiven.live/mcp/<marketplace>"
    }
  }
}

O segmento de caminho combina com os parâmetros de consulta acima, por exemplo https://mcp.aiven.live/mcp/gcp?services_scope=pg&read_only=true.

Opção 2: stdio (local)

Execute o servidor localmente como um processo filho do seu cliente MCP. Requer Node.js 18+.

Você deve fornecer seu token de API Aiven através da variável de ambiente AIVEN_TOKEN. Crie um token aqui.

Claude Code

claude mcp add --scope user aiven-mcp -e AIVEN_TOKEN=your-token-here -- npx -y mcp-aiven

Cursor, VS Code -- adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "aiven-mcp": {
      "command": "npx",
      "args": ["-y", "mcp-aiven"],
      "env": {
        "AIVEN_TOKEN": "your-token-here"
      }
    }
  }
}

Locais dos arquivos de configuração:

Cursor: Configurações do Cursor > Servidores MCP
VS Code: .vscode/mcp.json no seu workspace

Opção 3: Desenvolvimento local

Execute uma build local do servidor (útil para desenvolvimento e testes):

pnpm install && pnpm generate:api-types && pnpm generate && pnpm build && AIVEN_TOKEN="<YOUR_TOKEN>" MCP_TRANSPORT="http" PORT=3000 node dist/index.js

O servidor escuta na porta 3000 por padrão. Conecte seu cliente MCP a http://localhost:3000/mcp.

Para apontar uma implantação remota para um host personalizado (ex.: sua build local), defina MCP_HOST:

MCP_HOST=http://localhost:3000 node dist/index.js

Variáveis de Ambiente

Variável	Obrigatória	Padrão	Descrição
`AIVEN_TOKEN`	apenas stdio	--	Token de API Aiven (crie um aqui)
`AIVEN_READ_ONLY`	Não	`false`	Defina como `true` para expor apenas ferramentas somente leitura
`AIVEN_SERVICES_SCOPE`	Não	--	Escopos separados por vírgula para expor (ex.: `kafka`, `pg,kafka` ou `all`). Válidos: `all`, `core`, `pg`, `kafka`, `application`, `integrations`. `core` está sempre incluído. Omitir a variável ou definir `all` carrega todas as ferramentas.
`AIVEN_ALLOW_SECRETS`	Não	`false`	Defina como `true` para expor a ferramenta `aiven_service_connection_info`, que retorna credenciais ativas (senhas, URIs de conexão, certificados) na conversa. Desabilitado enquanto `AIVEN_READ_ONLY=true`.
`AIVEN_WRITE_ALLOWLIST`	Não	--	Nomes de ferramentas separados por vírgula para reabilitar enquanto `AIVEN_READ_ONLY=true` (ex.: `aiven_kafka_topic_create`). Ignorado quando o modo somente leitura não está habilitado.
`MCP_HOST`	Não	`https://mcp.aiven.live`	Substitui o host do recurso protegido OAuth
`MCP_TRANSPORT`	Não	`stdio`	Defina como `http` para iniciar um servidor HTTP em vez de stdio
`MCP_HTTP_RATE_LIMIT_MAX`	Não	`1000`	Máximo de requisições por janela em `POST /mcp` (transporte HTTP), por token bearer. Espera-se limitação de taxa por IP do cliente no Cloudflare.
`MCP_HTTP_RATE_LIMIT_WINDOW_MS`	Não	`60000`	Duração da janela em milissegundos para `MCP_HTTP_RATE_LIMIT_MAX`.
`EXTRA_PROTECTION`	Não	`false`	Defina como `true` em implantações HTTP para exigir um cabeçalho `X-Edge-Auth` válido em cada requisição, exceto `GET /health`. Veja Implantação da proteção de borda abaixo.
`MCP_EDGE_AUTH_SECRET`	Quando `EXTRA_PROTECTION=true`	--	Segredo compartilhado; deve corresponder ao valor que o Cloudflare injeta como `X-Edge-Auth` via Regras de Transformação.

No modo remoto (HTTP), AIVEN_TOKEN não é necessário. Seu cliente MCP envia seu token como um token Bearer a cada requisição.

O tráfego HTTP de produção é limitado por taxa em duas camadas: o Cloudflare impõe um limite por IP de cliente (configurado no painel do Cloudflare), e este servidor impõe MCP_HTTP_RATE_LIMIT_* por token bearer em POST /mcp.

Implantação da proteção de borda

Quando EXTRA_PROTECTION=true, qualquer incompatibilidade entre MCP_EDGE_AUTH_SECRET e o valor que o Cloudflare injeta como X-Edge-Auth faz com que todas as requisições retornem 403 (exceto GET /health). Ambos os valores são ambiente/config em lados opostos da conexão, então o único caminho de recuperação é corrigir o segredo e reimplantar ou atualizar o Cloudflare.

Habilite nesta ordem:

Regra de Transformação do Cloudflare — Adicione uma regra que defina X-Edge-Auth (e, se usado para ferramentas PG, X-Client-IP) no tráfego para a origem MCP. Anote o valor do segredo que você configurar.
MCP_EDGE_AUTH_SECRET — Implante o servidor com esta variável de ambiente definida com o mesmo segredo da Regra de Transformação. Deixe EXTRA_PROTECTION não definido ou false por enquanto; verifique se a origem ainda aceita tráfego.
EXTRA_PROTECTION=true — Habilite somente após as etapas 1–2 estarem ativas e correspondentes. Confirme se uma requisição MCP normal é bem-sucedida e o acesso direto à origem sem X-Edge-Auth é rejeitado.
Rotação de segredo — Atualize o Cloudflare e MCP_EDGE_AUTH_SECRET juntos (ou defina brevemente EXTRA_PROTECTION=false), reimplante e depois reabilite. Nunca rotacione apenas um lado enquanto a flag estiver ativa.

Se EXTRA_PROTECTION=true na inicialização e MCP_EDGE_AUTH_SECRET estiver ausente, o processo é encerrado imediatamente com um erro.

Enquanto as rejeições continuam, o servidor registra um aviso de configuração incorreta no máximo uma vez a cada 15 minutos (reiniciado após uma requisição com X-Edge-Auth válido), para que uma incompatibilidade de segredo fique visível nos logs sem uma linha por requisição rejeitada.

Ferramentas

Núcleo

Ferramenta	Descrição
`aiven_project_list`	Listar projetos
`aiven_project_get`	Obter detalhes do projeto
`aiven_list_project_clouds`	Listar plataformas de nuvem para um projeto
`aiven_project_vpc_list`	Listar VPCs para um projeto
`aiven_service_list`	Listar serviços
`aiven_service_type_plans`	Listar planos com disponibilidade na nuvem
`aiven_service_plan_pricing`	Obter preços de um plano em uma nuvem específica
`aiven_service_create`	Criar um serviço
`aiven_service_get`	Obter informações do serviço
`aiven_service_update`	Atualizar um serviço (plano, configuração, estado de energia)
`aiven_service_metrics_fetch`	Buscar métricas para serviços de dados gerenciados
`aiven_service_application_metrics_get`	Buscar métricas para serviços de aplicação
`aiven_project_get_service_logs`	Obter entradas de log do serviço
`aiven_service_query_activity`	Buscar consultas atuais para um serviço
`aiven_project_get_event_logs`	Obter entradas de log de eventos do projeto

Kafka

Ferramenta	Descrição
`aiven_kafka_topic_list`	Listar tópicos Kafka
`aiven_kafka_topic_create`	Criar um tópico Kafka
`aiven_kafka_topic_get`	Obter informações do tópico Kafka
`aiven_kafka_topic_update`	Atualizar um tópico Kafka
`aiven_kafka_topic_delete`	Excluir um tópico Kafka
`aiven_kafka_topic_message_list`	Ler mensagens de um tópico Kafka
`aiven_kafka_topic_message_produce`	Produzir mensagens em um tópico Kafka
`aiven_kafka_connect_available_connectors`	Listar tipos de conectores disponíveis
`aiven_kafka_connect_list`	Listar conectores em execução
`aiven_kafka_connect_create_connector`	Criar um conector
`aiven_kafka_connect_edit_connector`	Editar um conector
`aiven_kafka_connect_get_connector_status`	Obter status do conector
`aiven_kafka_connect_pause_connector`	Pausar um conector
`aiven_kafka_connect_resume_connector`	Retomar um conector
`aiven_kafka_connect_restart_connector`	Reiniciar um conector
`aiven_kafka_connect_delete_connector`	Excluir um conector
`aiven_kafka_schema_registry_subjects`	Listar assuntos do Schema Registry
`aiven_kafka_schema_registry_subject_version_get`	Obter versão do assunto do Schema Registry

PostgreSQL

Ferramenta	Descrição
`aiven_pg_service_available_extensions`	Listar extensões disponíveis
`aiven_pg_service_query_statistics`	Buscar estatísticas de consultas
`aiven_pg_bouncer_create`	Criar um pool de conexões PgBouncer
`aiven_pg_bouncer_update`	Atualizar um pool de conexões PgBouncer
`aiven_pg_bouncer_delete`	Excluir um pool de conexões PgBouncer
`aiven_pg_read`	Executar uma consulta SQL somente leitura
`aiven_pg_write`	Executar uma instrução SQL de escrita (INSERT, UPDATE, DELETE, CREATE TABLE, etc.)
`aiven_pg_optimize_query`	Otimização de consultas com IA (EverSQL)

Aplicações

Ferramenta	Descrição
`aiven_application_deploy`	Implantar uma aplicação Dockerizada na Aiven
`aiven_application_redeploy`	Reconstruir e reimplantar uma aplicação existente
`aiven_vcs_integration_list`	Listar contas VCS (GitHub) conectadas
`aiven_vcs_integration_repository_list`	Listar repositórios para uma integração VCS

Documentação

Ferramenta	Descrição
`aiven_docs_search`	Pesquisar a documentação oficial da Aiven em linguagem natural. Disponível apenas no servidor hospedado (`https://mcp.aiven.live/mcp`) — não exposto em implantações auto-hospedadas.

Contribuindo

Veja CONTRIBUTING.md para configuração de desenvolvimento, execução local e adição de novas ferramentas.

Licença

Apache-2.0