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.
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
- Claude Code
- Cursor
- Claude Desktop
- VS Code
- Gemini CLI
- Other clients
- Local installation
-
Open a terminal.
-
Choose your options, then run the generated command:
ServicesAccessRead and write. The assistant can create, modify, and delete.
⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.
Advanced settings
DevelopmentMarketplaceSelect 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" -
Run
claudeto start Claude Code. -
Run
/mcp, select aiven, and authenticate in your browser when prompted. -
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.
For one-click installation:
Add to CursorTo add the server manually:
- In your project root, create or edit the
.cursor/mcp.jsonfile. - Choose your options below, then copy the generated configuration into the file:
Read and write. The assistant can create, modify, and delete.
⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility. 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.Advanced settings
{
"mcpServers": {
"aiven": {
"type": "http",
"url": "https://mcp.aiven.live/mcp"
}
}
}
- Save the file.
- Restart Cursor.
- Open Settings > Tools & MCP.
- Select aiven and click Connect.
In Cursor Chat (Cmd+L / Ctrl+L), test the connection with a prompt such
as List my Aiven projects. and click Allow if prompted.
For more information, see the Cursor MCP documentation.
-
Open the Claude Desktop configuration file. If it does not exist, create it:
-
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json -
Windows:
%APPDATA%\Claude\claude_desktop_config.json
-
-
Choose your options, then add the generated configuration to the file:
ServicesAccessRead and write. The assistant can create, modify, and delete.
⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.
Advanced settings
DevelopmentMarketplaceSelect your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.
{"mcpServers": {"aiven": {"command": "npx","args": ["-y","mcp-remote","https://mcp.aiven.live/mcp"]}}} -
Save the file.
-
Restart Claude Desktop.
-
In a new conversation, test the connection with a prompt such as
List my Aiven projects.and click Allow if prompted.
For more information, see the Claude Desktop MCP documentation.
Requires VS Code 1.102 or later with the GitHub Copilot extension installed and enabled.
-
Open your workspace in VS Code.
-
In the workspace root, create a
.vscodedirectory. -
In the
.vscodedirectory, create or edit themcp.jsonfile. -
Choose your options, then add the generated configuration to the file:
ServicesAccessRead and write. The assistant can create, modify, and delete.
⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.
Advanced settings
DevelopmentMarketplaceSelect your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.
{"servers": {"aiven": {"type": "http","url": "https://mcp.aiven.live/mcp"}}} -
Save the file.
-
Reload VS Code.
-
Open the Command Palette, run MCP: List Servers, and confirm that aiven appears.
-
In Copilot Chat, test the connection with a prompt such as
List my Aiven projects.and click Allow if prompted.
For more information, see the VS Code MCP documentation.
-
Create or edit the
~/.gemini/settings.jsonfile. -
Choose your options, then add the generated configuration to the file:
ServicesAccessRead and write. The assistant can create, modify, and delete.
⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.
Advanced settings
DevelopmentMarketplaceSelect your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.
{"mcpServers": {"aiven": {"httpUrl": "https://mcp.aiven.live/mcp"}}} -
Save the file.
-
Run
geminito start the CLI. -
Run
/mcp auth aivento sign in through your browser. -
Test the connection with a prompt such as
List my Aiven projects.and approve the tool execution if prompted.
-
Open your MCP client configuration.
-
Choose your options, then add the generated configuration to your client:
ServicesAccessRead and write. The assistant can create, modify, and delete.
⚠ With full access, the assistant can create, modify, and delete services and data. Review security and responsibility.
Advanced settings
DevelopmentMarketplaceSelect your marketplace only if you subscribed to Aiven through AWS, Azure, or Google Cloud Marketplace. This helps you sign in to the correct console.
{"mcpServers": {"aiven": {"url": "https://mcp.aiven.live/mcp","oauth": {"oauthScopes": ["projects","services","accounts:read"]}}}}Most clients use a configuration similar to the preceding example.
-
Save the file and restart your client.
-
In your AI assistant, test the connection with a prompt such as
List my Aiven projects.and approve the tool execution if prompted.
Some clients require a transport type, such as "type": "http". If the configuration
fails, see your client documentation.
Use a local installation if you cannot use OAuth, for example in headless environments. The permissions of your API token apply.
Run the Aiven MCP server locally with npx instead of using the hosted server.
You need an Aiven API token
to authenticate requests to Aiven. Set AIVEN_READ_ONLY="true" to enable
read-only mode.
Set AIVEN_ALLOW_SECRETS="true" to let the AI agent access PostgreSQL and Kafka
connection credentials. Use this option only in development environments for
non-production services. For more information, see
Security and responsibility.
- Claude Code
- Cursor
- Claude Desktop
- VS Code
- Other clients
-
Open a terminal.
-
Run the following command, replacing
API_TOKENwith your Aiven API token:claude mcp add --scope user aiven-mcp -e AIVEN_TOKEN=API_TOKEN -e AIVEN_READ_ONLY=false -e AIVEN_ALLOW_SECRETS=false -- npx -y mcp-aiven -
Run
claudeto start Claude Code. -
Run
/mcpto verify that the server is registered.
-
In your project root, create or edit the
.cursor/mcp.jsonfile. -
Add the following configuration, replacing
API_TOKENwith your Aiven API token:{"mcpServers": {"aiven-mcp": {"command": "npx","args": ["-y", "mcp-aiven"],"env": {"AIVEN_TOKEN": "API_TOKEN","AIVEN_READ_ONLY": "false","AIVEN_ALLOW_SECRETS": "false"}}}} -
Save the file and restart Cursor.
-
Open the Claude Desktop configuration file.
-
Add the following configuration, replacing
API_TOKENwith your Aiven API token:{"mcpServers": {"aiven-mcp": {"command": "npx","args": ["-y", "mcp-aiven"],"env": {"AIVEN_TOKEN": "API_TOKEN","AIVEN_READ_ONLY": "false","AIVEN_ALLOW_SECRETS": "false"}}}} -
Save the file and restart Claude Desktop.
-
In the
.vscodedirectory, create or edit themcp.jsonfile. -
Add the following configuration, replacing
API_TOKENwith your Aiven API token:{"servers": {"aiven-mcp": {"command": "npx","args": ["-y", "mcp-aiven"],"env": {"AIVEN_TOKEN": "API_TOKEN","AIVEN_READ_ONLY": "false","AIVEN_ALLOW_SECRETS": "false"}}}} -
Save the file and reload VS Code.
-
Open your MCP client configuration.
-
Add the following configuration, replacing
API_TOKENwith your Aiven API token:{"mcpServers": {"aiven-mcp": {"command": "npx","args": ["-y", "mcp-aiven"],"env": {"AIVEN_TOKEN": "API_TOKEN"}}}} -
Save the file and restart your client.
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.
- In the organization, click Admin > Authentication.
- 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.
| Scope | Selector option | Description |
|---|---|---|
core | Always included | Tools for managing Aiven projects, services, plans, metrics, and logs |
pg | PostgreSQL | Tools for querying PostgreSQL databases, analyzing query performance, and managing extensions and connection pools |
kafka | Kafka | Tools for managing Apache Kafka topics, messages, connectors, and schemas |
application | Applications | Tools for deploying and redeploying applications and managing version control integrations |
integrations | Integrations | Tools for managing service integrations and listing available integration and endpoint types |
opensearch | OpenSearch | Includes only the core tools; no OpenSearch-specific tools are currently available |
context | Context Early availability | Tools for searching data assets, viewing lineage, and updating asset descriptions and tags |
all | All | All available tools (default) |
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
corescope is always included, even if you don't specify it. - You can combine scopes. For example,
pg,kafkaloads thecore, PostgreSQL, and Kafka tools. - You can't combine
allwith 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
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
- Aiven MCP use cases: Examples of what you can do with Aiven MCP
- Aiven MCP announcement: Overview of what Aiven MCP can do
- PostgreSQL MCP server blog post: Use Aiven MCP with PostgreSQL
- Kafka MCP blog post: Use Aiven MCP with Apache Kafka