Aiven

Servidor MCP Aiven

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

Gerencie PostgreSQL, Apache Kafka, aplicativos 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, excluir 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 é governado 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 realizar.

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 acesso a agentes de IA 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 nas configurações MCP do Cursor:

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

VS Code / Copilot

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

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

Modo Somente Leitura (Remoto)

Ative 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 Escopadas (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) é sempre incluído implicitamente.

Escopos válidos: all, core, pg, kafka, application, integrations. Use all para carregar explicitamente todas as ferramentas (equivalente a 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 reativar ferramentas de escrita específicas enquanto mantém todo o resto 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 de Marketplace (Remoto)

Se você assinou a Aiven por meio 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 por meio 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 compilação 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 (por exemplo, sua compilação 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	somente 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 (por exemplo, kafka, pg,kafka ou all). Válidos: all, core, pg, kafka, application, integrations. core é 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 ao vivo (senhas, URIs de conexão, certificados) na conversa. Desabilitada enquanto AIVEN_READ_ONLY=true.
AIVEN_WRITE_ALLOWLIST	Não	--	Nomes de ferramentas separados por vírgula para reativar enquanto AIVEN_READ_ONLY=true (por exemplo, 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 solicitações por janela em POST /mcp (transporte HTTP), por token de portador. A limitação de taxa por IP do cliente é esperada 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 solicitação, exceto GET /health. Consulte Implantação de 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 por meio de Regras de Transformação.

No modo remoto (HTTP), AIVEN_TOKEN não é necessário. Seu cliente MCP envia seu token como um token de portador em cada solicitação.

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

Implantação de 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 cada solicitação retorne 403 (exceto GET /health). Ambos os valores são ambiente/configuração 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:

1. Regra de Transformação do Cloudflare — Adicione uma regra que define 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.
2. 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.
3. EXTRA_PROTECTION=true — Habilite somente após as etapas 1–2 estarem ativas e correspondentes. Confirme que uma solicitação MCP normal é bem-sucedida e que o acesso direto à origem sem X-Edge-Auth é rejeitado.
4. Rotação de segredo — Atualize o Cloudflare e MCP_EDGE_AUTH_SECRET juntos (ou defina brevemente EXTRA_PROTECTION=false), reimplante e reative. Nunca rotacione apenas um lado enquanto o sinalizador estiver ativo.

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

Enquanto as rejeições continuarem, o servidor registra um aviso de configuração incorreta no máximo uma vez a cada 15 minutos (redefinido após uma solicitação com X-Edge-Auth válido), para que uma incompatibilidade de segredo seja visível nos logs sem uma linha por solicitaçã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 de nuvem
aiven_service_plan_pricing	Obter preços para 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 aplicativos
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)

Aplicativos

Ferramenta	Descrição
aiven_application_create	Criar e implantar inicialmente um aplicativo Containerfile/Dockerfile; retorna 409 se o serviço já existir
aiven_application_redeploy	Reconstruir um aplicativo existente a partir do repositório configurado sem alterar a configuração do serviço
aiven_vcs_integration_list	Listar contas VCS (GitHub) conectadas
aiven_vcs_integration_repository_list	Listar repositórios para uma integração VCS
aiven_vcs_integration_repository_branch_list	Listar ramificações do repositório e seus SHAs de commit atuais
aiven_vcs_integration_repository_container_manifest_files_list	Encontrar manifestos candidatos de Containerfile, Dockerfile e Compose
aiven_vcs_integration_repository_scan_container_manifest	Derivar configurações candidatas de serviço Aiven de um Containerfile, Dockerfile ou partes suportadas de um arquivo Compose

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 exposta em implantações auto-hospedadas.

Contribuindo

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

Licença

Apache-2.0