diff --git a/docs/get-started.md b/docs/get-started.md index 888fdd5ed..7751d2a58 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -8,6 +8,7 @@ import {ButtonSecondary} from "@site/src/components/Buttons"; import Card from "@site/src/components/Card"; import Overview from "@site/static/images/content/platform/platform-overview.png"; import GridContainer from "@site/src/components/GridContainer"; +import AI from "@site/static/images/logos/star-ai.svg"; import K8sIcon from "@site/static/images/logos/kubernetes.svg"; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -292,6 +293,17 @@ Create a service using the Aiven CLI or API. /> +Create and manage services using AI assistants. + + + + + ### Step 6: Earn credits by referring others to Aiven Invite colleagues and friends to sign up to Aiven. diff --git a/docs/products/kafka/get-started/get-started-kafka.md b/docs/products/kafka/get-started/get-started-kafka.md index 7b0bcc2bd..dfe6b6769 100644 --- a/docs/products/kafka/get-started/get-started-kafka.md +++ b/docs/products/kafka/get-started/get-started-kafka.md @@ -70,3 +70,15 @@ Produce data manually to test application integrations or custom workloads. - Use this approach for development, automation, or advanced testing scenarios. **Next step:** [Generate sample data manually with Docker](/docs/products/kafka/howto/generate-sample-data-manually). + +## Create and manage Kafka using AI assistants + +Use the [Aiven MCP server](/docs/tools/mcp) to create Kafka services, manage +topics, produce and consume messages, and configure connectors from MCP-compatible +clients such as Cursor, Claude Code, and VS Code. + +- Configure the Aiven MCP server in your AI assistant. +- Describe the service or operation you want in natural language. +- The assistant creates and manages Kafka resources through the Aiven API. + +**Next step:** [Set up the Aiven MCP server](/docs/tools/mcp). diff --git a/docs/products/postgresql/get-started.md b/docs/products/postgresql/get-started.md index 494732637..795e6827c 100644 --- a/docs/products/postgresql/get-started.md +++ b/docs/products/postgresql/get-started.md @@ -30,6 +30,12 @@ Start using Aiven for PostgreSQL® by creating a service, connecting to it, and - A [personal token](https://docs.aiven.io/docs/platform/howto/create_authentication_token.html) - [psql](https://www.postgresql.org/download/) command line tool installed + + + +- An MCP-compatible client such as Cursor, Claude Code, Claude Desktop, or VS Code +- The [Aiven MCP server](/docs/tools/mcp) configured in your client + @@ -62,6 +68,17 @@ The following example files are also available in the + + + +Open your AI assistant and describe the service you want to create. For example: + +> Create an Aiven for PostgreSQL service named `my-pg` in the `google-europe-west1` +> region using the `hobbyist` plan. + +The assistant uses the Aiven MCP server to create the service. For setup instructions, +see [Aiven MCP server](/docs/tools/mcp). + diff --git a/docs/tools.md b/docs/tools.md index 8547b0ade..2dc64dadc 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -41,10 +41,16 @@ You can interact with the Aiven platform with various interfaces and tools that title="SQL query optimizer" description="Use AI to optimize your queries." /> + diff --git a/docs/tools/mcp-server.md b/docs/tools/mcp-server.md index 294eb260a..30cd265b4 100644 --- a/docs/tools/mcp-server.md +++ b/docs/tools/mcp-server.md @@ -1,6 +1,6 @@ --- title: Connect to Aiven documentation using MCP -sidebar_label: MCP server +sidebar_label: Documentation MCP server --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; diff --git a/docs/tools/mcp.md b/docs/tools/mcp.md new file mode 100644 index 000000000..4ed9a3bb3 --- /dev/null +++ b/docs/tools/mcp.md @@ -0,0 +1,227 @@ +--- +title: Manage Aiven services using MCP +sidebar_label: Aiven MCP server +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +{/* Update mcpUrl to change the MCP server URL across all code samples on this page. */} +export const mcpUrl = "https://aiven.io/mcp"; +export const cursorDeepLink = `cursor://anysphere.cursor-deeplink/mcp/install?name=aiven-mcp&config=${typeof btoa !== "undefined" ? btoa(JSON.stringify({url: mcpUrl})) : ""}`; + +The Aiven MCP server lets you create and manage services directly from AI assistants such as Cursor and Claude Code. + +## Prerequisites + +- An [Aiven account](https://console.aiven.io/signup) +- An organization with MCP access enabled +- An MCP-compatible client such as Cursor, Claude Code, Claude Desktop, or VS Code + +## MCP server URL + +Use the following server URL when configuring your client: + +{mcpUrl} + +## Configure your MCP client + + + + + + + + + Add to Cursor + + +

+ +Alternatively, add it manually: + +1. In your project root, create or edit `.cursor/mcp.json`. +1. Add the following configuration: + + {JSON.stringify({mcpServers: {aiven: {type: "http", url: mcpUrl}}}, null, 2)} + +1. Save the file. +1. Restart Cursor. +1. Open **Settings** > **Tools & MCP**. +1. Select **aiven** and click **Connect**. + + + + +1. Open a terminal. +1. Run the following command: + + {`claude mcp add --transport http aiven ${mcpUrl}`} + +1. Run `/mcp` in Claude Code to verify the server is registered. +1. On first use, a browser window opens where you sign in to Aiven and select your organization. + +For more information, see the [Claude Code MCP documentation](https://docs.anthropic.com/en/docs/claude-code/tutorials/set-up-mcp). + + + + +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` + +1. Add the following to the configuration file: + + {JSON.stringify({mcpServers: {aiven: {type: "http", url: mcpUrl}}}, null, 2)} + +1. Save the file and restart Claude Desktop. + +For more information, see the [Claude Desktop MCP documentation](https://modelcontextprotocol.io/quickstart/user). + + + + +:::note +Requires Visual Studio Code 1.102 or later with the GitHub Copilot extension installed +and enabled. +::: + +1. Open your workspace in Visual Studio Code. +1. In the workspace root, create a `.vscode` directory if it does not exist. +1. In the `.vscode` directory, create or edit `mcp.json`. +1. Add the following configuration: + + {JSON.stringify({servers: {aiven: {type: "http", url: mcpUrl}}}, null, 2)} + +1. Save the file. +1. Reload Visual Studio Code. +1. Open the Command Palette and run **MCP: List Servers**. +1. Confirm that **aiven** appears in the list. + +For more information, see the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers). + + + + +1. Open your MCP client configuration. +1. Add the Aiven MCP server using the following URL: + + {mcpUrl} + +Most clients accept a configuration similar to: + +{JSON.stringify({mcpServers: {aiven: {url: mcpUrl}}}, null, 2)} + +1. Save the file and restart your client. + +Some clients require specifying the transport type, for example `"type": "http"`. Refer +to your client documentation if the configuration fails. + + + + +## Verify the connection + + + + +1. Open Cursor Chat with **Cmd+L** on macOS or **Ctrl+L** on Windows/Linux. +1. Try a prompt such as: + + > List my Aiven projects. + +1. If prompted to allow tool execution, click **Allow**. +1. To confirm the server is registered, go to **Settings** > **Tools & MCP** and + check that **aiven** appears with a connected status. + + + + +1. Run `/mcp` in Claude Code to verify the server is registered. +1. Try a prompt such as: + + > List my Aiven projects. + +1. If prompted to allow tool execution, confirm. + + + + +1. Open a new conversation. +1. Verify that the MCP tools icon appears in the input area. +1. Try a prompt such as: + + > List my Aiven projects. + +1. If prompted to allow tool execution, click **Allow**. + + + + +1. Open Copilot Chat in Visual Studio Code. +1. Open the Command Palette and run **MCP: List Servers**. +1. Confirm that **aiven** appears in the list. +1. Try a prompt such as: + + > List my Aiven projects. + +1. If prompted to allow tool execution, click **Allow**. + + + + +1. Open your AI assistant. +1. Try a prompt such as: + + > List my Aiven projects. + +1. If prompted to allow tool execution, confirm. +1. Verify that the response includes information about your Aiven projects. + + + + +## Authentication + +The Aiven MCP server uses OAuth 2.0 with PKCE for authentication. When you +first use the server, it opens a browser window where you sign in to Aiven and +select your organization. The server manages token refresh automatically. + +## Supported tools + +### Service management + +Create, update, and delete Aiven services across all supported service types. +Browse available plans and pricing, view service metrics and logs, and manage +service configurations and cloud regions. + +### PostgreSQL® + +Create and manage PostgreSQL databases, execute read and write SQL queries, +and manage PgBouncer connection pools. Get AI-powered query optimization +recommendations, view query performance statistics, and list available extensions. + +### Apache Kafka® + +Create and manage Kafka topics, produce and consume messages, and configure +Kafka Connect connectors. Browse Schema Registry subjects and manage +connector lifecycle operations including pause, resume, and restart. + +## Read-only mode + +To restrict the server to read-only operations, set the `AIVEN_READ_ONLY` +environment variable to `true` in your MCP client configuration: + +{JSON.stringify({mcpServers: {aiven: {type: "http", url: mcpUrl, env: {AIVEN_READ_ONLY: "true"}}}}, null, 2)} + +In read-only mode, the server only allows operations that read data, such as +listing services, viewing metrics, and running SELECT queries. Write +operations like creating services or modifying data are blocked. diff --git a/sidebars.ts b/sidebars.ts index 0d1924ba2..f3dbd7241 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -524,6 +524,7 @@ const sidebars: SidebarsConfig = { ], }, 'tools/query-optimizer', + 'tools/mcp', 'tools/mcp-server', 'tools/doc-diff-llms', ], diff --git a/static/images/logos/cursor.svg b/static/images/logos/cursor.svg new file mode 100644 index 000000000..7b90cd616 --- /dev/null +++ b/static/images/logos/cursor.svg @@ -0,0 +1,3 @@ + + +