Skip to main content

Aiven MCP server for managed services

Aiven MCP is a Model Context Protocol (MCP) server that lets AI assistants such as Cursor and Claude Code create and manage Aiven services, including PostgreSQL®, Apache Kafka®, and OpenSearch®. For PostgreSQL and Kafka, you can also work with the data in your services. You can view service status, metrics, logs, and configuration, and manage services and plans.

To start, see Install Aiven MCP. To control which operations your assistant can perform, use read-only mode and service scopes.

What Aiven MCP can do​

After you connect an AI assistant to Aiven MCP, you can use natural language to work with your Aiven resources.

  • View resources: List projects, services, and integrations, and check the status, plan, and cloud region of a service.
  • Manage services: Create, update, and delete services such as Aiven for PostgreSQL®, Aiven for Apache Kafka®, and Aiven for OpenSearch®. Change service plans and compare plans and pricing.
  • Troubleshoot services: Review service metrics, logs, and configuration.
  • Work with PostgreSQL: Run read-only SQL queries, find slow queries and missing indexes, and manage extensions such as pgvector.
  • Work with Apache Kafka: List topics and consumer groups, inspect consumer lag, produce and read messages, inspect schemas, and manage Kafka Connect connectors.
  • Deploy applications: Deploy applications to Aiven Runtime.
  • Search the Aiven documentation: Ask questions about Aiven and get answers from the documentation.
  • Search and update cataloged context: Search data assets such as tables, topics, and schemas, explore data lineage, and update asset descriptions and tags using Aiven Context.

Prerequisites​

  • An Aiven account. Aiven MCP is included with your account at no extra cost.
  • An MCP-compatible client, such as Cursor, Claude Code, Claude Desktop, VS Code, or Gemini CLI.
  • MCP connections enabled for your organization. If you created your Aiven account, you're the organization admin and can enable them in the Aiven Console: click Admin > Authentication > Allow MCP connections. Otherwise, ask your organization admin to enable them.

Authentication uses OAuth 2.0 with PKCE. When you authenticate a client for the first time, your browser opens so you can sign in and authorize MCP access. This is usually a one-time setup step per client.

Note

Aiven owns the aiven.live domain and operates the hosted MCP server at mcp.aiven.live. The server uses the Aiven API at api.aiven.io for authorization.

Install Aiven MCP​

  1. Open a terminal.

  2. Choose your options, then run the generated command:

    Read and write. The assistant can create, modify, and delete.

    Advanced settings

    Select your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.

    claude mcp add --transport http aiven "https://mcp.aiven.live/mcp"
  3. Run claude to start Claude Code.

  4. Run /mcp, select aiven, and authenticate in your browser when prompted.

  5. Test the connection with a prompt such as List my Aiven projects. and approve the tool execution if prompted.

For more information, see the Claude Code MCP documentation.

Example prompts​

After you connect your AI assistant to Aiven MCP, try these prompts to explore, manage, and troubleshoot your Aiven resources. Some prompts require specific service scopes or write access.

Explore your Aiven resources​

List your projects​

List my Aiven projects.

Lists the projects you can access and verifies that the MCP connection works.

Inspect a service​

Show me the status and configuration of my Aiven service SERVICE_NAME.

Replace SERVICE_NAME with the name of an existing service.

Read Kafka messages​

Show me the latest available messages from the TOPIC_NAME topic
in my Aiven for Apache Kafka service SERVICE_NAME.

Replace SERVICE_NAME with your Kafka service name and TOPIC_NAME with an existing topic name. Requires the kafka or all scope.

Find data assets and lineage​

Search for data assets related to orders in my Aiven organization and show their lineage.

Requires the context or all scope and access to Aiven Context.

Manage Aiven services​

Create a PostgreSQL service​

Create a PostgreSQL service in REGION.

Replace REGION with your preferred cloud region. Requires write access. If read-only mode is enabled, the assistant cannot create services unless the operation is explicitly allowed.

Monitor and troubleshoot services​

Find slow PostgreSQL queries​

Inspect my Aiven for PostgreSQL service for the slowest queries using
pg_stat_statements. Show total time, calls, and mean time, and suggest
indexes or rewrites for the worst offenders.

Retrieves query statistics and suggests optimizations. Requires the pg or all scope.

Investigate Kafka consumer lag​

Check my Aiven for Apache Kafka services for consumer groups with high lag.
For each affected topic, report the group, partition, and current lag, and
suggest likely causes.

Reports consumer groups with high lag and suggests causes. Requires the kafka or all scope.

Check service health​

Give me a health summary of every service in my Aiven project: state, plan,
maintenance updates pending, and any nodes that are not running.

Summarizes the state of each service and highlights issues. Requires the core scope, which is always included.

Read-only mode​

Read-only mode restricts MCP tools to viewing services and other resources. You cannot create, modify, or delete resources. Read-only mode applies at the organization level and the client level.

PostgreSQL read queries and the Aiven Context search and lineage tools still work in read-only mode. To allow selected write operations at the client level, see Allow specific write operations.

Organization level​

Organization admins can restrict MCP connections to read-only operations for all users in the organization.

  1. In the organization, click Admin > Authentication.
  2. Select Restrict MCP connections to read-only operations.

This policy overrides client-level settings, including any write allowlist. Users cannot enable write operations when the organization policy requires read-only access.

For more information, see Set authentication policies for organization users.

Client level​

In Install Aiven MCP, use the Access options to configure your client:

  • Full access: Makes write tools available, subject to your Aiven user permissions.
  • Read-only: Excludes tools that modify resources or data.
  • Read-only, plus specific writes: Excludes write tools except those you select.

These settings apply only to your client and cannot override an organization-level restriction.

To configure read-only mode manually, add read_only=true to the hosted server URL or set AIVEN_READ_ONLY=true for a local installation. You can combine read-only mode with service scopes:

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

Limit tool access​

Use service scopes to control which tools are available to your AI assistant. Each tool performs a specific action, such as listing services or creating a Kafka topic.

Service scopes don't change your Aiven user permissions. The MCP server can perform only the actions that your authenticated user is authorized to perform.

Available service scopes​

Use the Services options in Install Aiven MCP to select which groups of tools are available to your AI assistant.

ScopeSelector optionDescription
coreAlways includedTools for managing Aiven projects, services, plans, metrics, and logs
pgPostgreSQLTools for querying PostgreSQL databases, analyzing query performance, and managing extensions and connection pools
kafkaKafkaTools for managing Apache Kafka topics, messages, connectors, and schemas
applicationApplicationsTools for deploying and redeploying applications and managing version control integrations
integrationsIntegrationsTools for managing service integrations and listing available integration and endpoint types
opensearchOpenSearchIncludes only the core tools; no OpenSearch-specific tools are currently available
contextContext Early availabilityTools for searching data assets, viewing lineage, and updating asset descriptions and tags
allAllAll available tools (default)
Note

Aiven Context is in early availability. To use the context scope, your organization must have Aiven Context enabled. Contact your Aiven account team to request access.

When configuring service scopes:

  • The core scope is always included, even if you don't specify it.
  • You can combine scopes. For example, pg,kafka loads the core, PostgreSQL, and Kafka tools.
  • You can't combine all with other scopes. Doing so returns an error.
  • If you don't specify a scope, Aiven MCP loads all available tools.

For the full list of available tools and their descriptions, see Available MCP tools.

Configure service scopes​

When you select service scopes in Install Aiven MCP, the generated configuration includes the corresponding settings. Selecting All doesn't add a services_scope parameter.

To configure service scopes manually on the hosted server, add the services_scope parameter to the server URL. Separate multiple scopes with commas.

For example, to load Kafka tools:

https://mcp.aiven.live/mcp?services_scope=kafka

To load both PostgreSQL and Kafka tools:

https://mcp.aiven.live/mcp?services_scope=pg,kafka

For a local installation, set the AIVEN_SERVICES_SCOPE environment variable in the env section of your MCP client configuration:

{
"mcpServers": {
"aiven-mcp": {
"command": "npx",
"args": ["-y", "mcp-aiven"],
"env": {
"AIVEN_TOKEN": "API_TOKEN",
"AIVEN_SERVICES_SCOPE": "pg,kafka"
}
}
}
}

Replace API_TOKEN with your Aiven API token. This example uses the mcpServers format. For VS Code, use servers instead.

To verify which tools are available, open your MCP client's tool list.

Allow specific write operations​

To allow selected write operations while your client is in read-only mode, choose Read-only, plus specific writes under Access in Install Aiven MCP.

To allow specific write operations on the hosted server, enable read-only mode and add the permitted tool names to the write_allowlist URL parameter, separated by commas. For example, to allow Kafka topic creation:

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

For a local installation, set the AIVEN_WRITE_ALLOWLIST environment variable. The write allowlist applies only when read-only mode is enabled. For supported tool names, see Available MCP tools.

The write allowlist doesn't grant additional Aiven permissions. Your user must still have permission to perform each allowed operation. An organization-level read-only policy takes precedence over the write allowlist.

Security and responsibility​

Important

MCP tools can perform destructive operations on your Aiven services, including creating, modifying, and deleting services, databases, topics, and data.

AI agents run operations from natural language prompts, which can be misinterpreted. Using the Aiven MCP server can result in damage to or loss of data.

Aiven secures the MCP server and data in transit. Your selected AI agent provider determines how the agent uses your data, including whether it uses that data for training. Review the provider's terms before you enable the integration.

Under the shared responsibility model, security and compliance for MCP usage are shared between Aiven and your organization. Aiven secures the platform and API. You are responsible for the following:

  • Decide on MCP access. Evaluate whether to enable MCP in your organization and the associated risks.
  • Control access. Scope API tokens to the minimum permissions needed and rotate them regularly.
  • Review AI agent actions. Review actions before they run, especially write or delete operations on production resources.
  • Limit write access. Use read-only mode at the organization level for all users, or at the client level for an individual client.
  • Keep credentials off in production. The Allow connection credentials option (allow_secrets=true) returns PostgreSQL and Kafka connection credentials, including URIs, passwords, and certificates, to the AI agent. Use it only for development with non-production services that do not hold sensitive data.

The Aiven MCP server can also connect directly to PostgreSQL services running in a private VPC.

Related pages