Aiven

Servidor MCP da 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 da 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 da 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 dos 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 da Aiven associadas à conta autenticada. O servidor MCP só pode executar ações que o seu usuário da Aiven tem permissão para fazer.

Segurança de agentes 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 o 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 conceder 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)

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 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 da Aiven e quer 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, opensearch. Use all para carregar explicitamente todas as ferramentas (o mesmo que omitir o parâmetro). all não pode ser combinado com outros escopos. opensearch segue as mesmas regras que kafka ou pg (ferramentas principais mais as da categoria OpenSearch); ainda não há ferramentas específicas de OpenSearch, então atualmente ele expõe apenas as principais.

{
  "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 mantendo todo o restante em somente leitura. Útil quando você quer acesso majoritariamente de leitura mas ainda precisa permitir uma ação de escrita, por exemplo criar tópicos do Kafka. Combine vários nomes de ferramentas com vírgulas. Ignorado quando read_only não está ativado.

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 o 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 se 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 da 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: Cursor Settings > MCP Servers
• 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 (por exemplo, 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 da 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 a expor (por exemplo, kafka, pg,kafka ou all). Válidos: all, core, pg, kafka, application, integrations, opensearch. core é incluído implicitamente para tipos de serviço com escopo. opensearch ainda não tem ferramentas dedicadas (apenas as principais até que ferramentas de OpenSearch sejam adicionadas). 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) para a conversa. Desativada enquanto AIVEN_READ_ONLY=true.
AIVEN_WRITE_ALLOWLIST	Não	--	Nomes de ferramentas separados por vírgula a reativar enquanto AIVEN_READ_ONLY=true (por exemplo, aiven_kafka_topic_create). Ignorado quando o modo somente leitura não está ativado.
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 de portador. A limitação de taxa por IP do cliente é esperada na 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 a Cloudflare injeta como X-Edge-Auth via Transform Rules.

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

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

Implantação da proteção de borda

Quando EXTRA_PROTECTION=true, qualquer divergência entre MCP_EDGE_AUTH_SECRET e o valor que a Cloudflare injeta como X-Edge-Auth faz com que toda requisiçã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 a Cloudflare.

Ative nesta ordem:

1. Regra de Transformação da Cloudflare — Adicione uma regra que define X-Edge-Auth (e, se usado para ferramentas PG, X-Client-IP) no tráfego para a origem do 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 definida ou como false por enquanto; verifique se a origem ainda aceita tráfego.
3. EXTRA_PROTECTION=true — Ative somente depois que os passos 1–2 estiverem ativos e correspondentes. Confirme que uma requisição MCP normal é bem-sucedida e que o acesso direto à origem sem X-Edge-Auth é rejeitado.
4. Rotação de segredo — Atualize a Cloudflare e MCP_EDGE_AUTH_SECRET juntas (ou defina brevemente EXTRA_PROTECTION=false), reimplante e então reative. Nunca rotacione um lado sozinho enquanto a flag estiver ativada.

Se EXTRA_PROTECTION=true na inicialização e MCP_EDGE_AUTH_SECRET estiver ausente, o processo encerra 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 requisição com X-Edge-Auth válido), para que uma divergência de segredo fique visível nos logs sem uma linha por requisição rejeitada.

Ferramentas

Principais

Ferramenta	Descrição
aiven_project_list	Listar projetos
aiven_project_get	Obter detalhes do projeto
aiven_list_project_clouds	Listar plataformas de nuvem de um projeto
aiven_project_vpc_list	Listar VPCs de um projeto
aiven_service_list	Listar serviços
aiven_service_type_plans	Listar planos com disponibilidade por nuvem
aiven_service_type_get	Obter versões padrão e disponíveis do mecanismo para um tipo de serviço
aiven_service_plan_pricing	Obter preço 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 de serviços de dados gerenciados
aiven_service_application_metrics_get	Buscar métricas de serviços de aplicação
aiven_project_get_service_logs	Obter entradas de log do serviço
aiven_service_query_activity	Buscar consultas atuais de um serviço
aiven_project_get_event_logs	Obter entradas do log de eventos do projeto

Kafka

Ferramenta	Descrição
aiven_kafka_topic_list	Listar tópicos do Kafka
aiven_kafka_topic_create	Criar um tópico do Kafka
aiven_kafka_topic_get	Obter informações de um tópico do Kafka
aiven_kafka_topic_update	Atualizar um tópico do Kafka
aiven_kafka_topic_delete	Excluir um tópico do Kafka
aiven_kafka_topic_message_list	Ler mensagens de um tópico do Kafka
aiven_kafka_topic_message_produce	Produzir mensagens em um tópico do Kafka
aiven_kafka_connect_available_connectors	Listar tipos de conector 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 de um 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 um comando 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_create	Criar e implantar inicialmente uma aplicação Containerfile/Dockerfile; retorna 409 se o serviço já existir
aiven_application_redeploy	Recompilar uma aplicação existente a partir do repositório configurado sem alterar a configuração do serviço
aiven_vcs_integration_initialize	Iniciar o fluxo baseado em navegador para conectar uma conta do GitHub
aiven_vcs_integration_list	Listar contas de VCS (GitHub) conectadas
aiven_vcs_integration_repository_list	Listar repositórios de uma integração de VCS
aiven_vcs_integration_repository_branch_list	Listar branches do repositório e seus SHAs de commit atuais
aiven_vcs_integration_repository_container_manifest_files_list	Encontrar candidatos a Containerfile, Dockerfile e manifestos Compose
aiven_vcs_integration_repository_scan_container_manifest	Derivar configurações candidatas de serviço da Aiven a partir 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

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

Licença

Apache-2.0