Aiven MCP

Create and manage Aiven services from AI assistants such as Cursor and Claude Code, including PostgreSQL®, Apache Kafka®, plans, metrics, logs, and service configuration. Use read-only mode to limit MCP tools to viewing services and other resources. You can enable it in your client or as an organization policy. You can also limit tools to specific services to keep the assistant focused.

Prerequisites

• An Aiven account
• An MCP-compatible client, such as Cursor, Claude Code, Claude Desktop, VS Code, or Gemini CLI
• MCP access enabled for your organization by an organization admin. In the Aiven Console, click Admin > Authentication > Allow MCP connections.

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 the Aiven MCP

Claude Code

1. Open a terminal.

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

   Services

   AllPostgreSQLKafkaIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   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.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   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.

Cursor

For one-click installation:

Add to Cursor

To add the server manually:

1. In your project root, create or edit the .cursor/mcp.json file.
2. Choose your options below, then copy the generated configuration into the file:

Services

AllPostgreSQLKafkaIntegrations

AccessRead-onlyRead-only, plus specific writesFull access

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.

Advanced settings

DevelopmentAllow connection credentials (development only)

MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

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.

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

3. Save the file.
4. Restart Cursor.
5. Open Settings > Tools & MCP.
6. 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.

Claude Desktop

1. 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

2. Choose your options, then add the generated configuration to the file:

   Services

   AllPostgreSQLKafkaIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   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.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   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.

   {
     "mcpServers": {
       "aiven": {
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://mcp.aiven.live/mcp"
         ]
       }
     }
   }

3. Save the file.

4. Restart Claude Desktop.

5. 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.

VS Code

note

Requires VS Code 1.102 or later with the GitHub Copilot extension installed and enabled.

1. Open your workspace in VS Code.

2. In the workspace root, create a .vscode directory.

3. In the .vscode directory, create or edit the mcp.json file.

4. Choose your options, then add the generated configuration to the file:

   Services

   AllPostgreSQLKafkaIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   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.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   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.

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

5. Save the file.

6. Reload VS Code.

7. Open the Command Palette, run MCP: List Servers, and confirm that aiven appears.

8. 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.

Gemini CLI

1. Create or edit the ~/.gemini/settings.json file.

2. Choose your options, then add the generated configuration to the file:

   Services

   AllPostgreSQLKafkaIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   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.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   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.

   {
     "mcpServers": {
       "aiven": {
         "httpUrl": "https://mcp.aiven.live/mcp"
       }
     }
   }

3. Save the file.

4. Run gemini to start the CLI.

5. Run /mcp auth aiven to sign in through your browser.

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

Other clients

1. Open your MCP client configuration.

2. Choose your options, then add the generated configuration to your client:

   Services

   AllPostgreSQLKafkaIntegrations

   AccessRead-onlyRead-only, plus specific writesFull access

   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.

   Advanced settings

   DevelopmentAllow connection credentials (development only)

   MarketplaceNone (Aiven)AWS MarketplaceAzure MarketplaceGoogle Cloud Marketplace

   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.

   {
     "mcpServers": {
       "aiven": {
         "url": "https://mcp.aiven.live/mcp",
         "oauth": {
           "oauthScopes": [
             "projects",
             "services",
             "accounts:read"
           ]
         }
       }
     }
   }

   Most clients use a configuration similar to the preceding example.

3. Save the file and restart your client.

4. 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.

Local installation

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

1. Open a terminal.

2. Run the following command, replacing your-token-here with your Aiven API token:

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

3. Run claude to start Claude Code.

4. Run /mcp to verify that the server is registered.

Cursor

1. In your project root, create or edit the .cursor/mcp.json file.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

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

3. Save the file and restart Cursor.

Claude Desktop

1. Open the Claude Desktop configuration file.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

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

3. Save the file and restart Claude Desktop.

VS Code

1. In the .vscode directory, create or edit the mcp.json file.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

   {
     "servers": {
       "aiven-mcp": {
         "command": "npx",
         "args": ["-y", "mcp-aiven"],
         "env": {
           "AIVEN_TOKEN": "your-token-here",
           "AIVEN_READ_ONLY": "false",
           "AIVEN_ALLOW_SECRETS": "false"
         }
       }
     }
   }

3. Save the file and reload VS Code.

Other clients

1. Open your MCP client configuration.

2. Add the following configuration, replacing your-token-here with your Aiven API token:

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

3. Save the file and restart your client.

What Aiven MCP can do

After you connect to Aiven MCP, you can work with Aiven resources in natural language. For example, you can do the following:

• View resources: List projects, services, and integrations, or check the status, plan, and cloud region of a service.
• Manage services: Create, update, and delete services such as PostgreSQL® and Apache Kafka®. You can also change service plans and configuration. Read-only mode restricts MCP tools to read-only operations, such as viewing services and other resources.
• Inspect and troubleshoot services: View service metrics, logs, and configuration to investigate issues.
• Use Aiven documentation: Ask questions and get answers based on the Aiven documentation.

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.

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.

Users cannot override this setting in their client configuration. Write operations fail even if a user configures their client without read-only mode.

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

Client level

You can enable read-only mode for your client in the installation configuration. The setting applies only to that client and does not change the organization policy. It cannot override an organization-level restriction.

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.