Aiven Management Proxy Service (AMPS)

This project encapsulates an MCP server within a Docker environment to manage and query Aiven resources.

Deployment Procedure

1. Establish a configuration file named .env furnishing your requisite Aiven access credentials:

bash

Aiven API Connection Details

AIVEN_BASE_URL="https://api.aiven.io" AIVEN_PROJECT_NAME="your-designated-project"

Aiven Authentication Credential

AIVEN_TOKEN="your-secret-token-here"

1. Initiate the Docker container using Docker Compose:

bash docker-compose up -d

1. The operational server endpoint will be available at: http://localhost:8000

Server Access Points

• GET /: Renders an introductory HTML page displaying the current server operational status and configuration parameters.
• GET /api/projects: Returns an array of JSON objects detailing all accessible Aiven projects.

Terminating the Service

bash docker-compose down

Aiven MCP Backend

This is the core MCP server component dedicated to Aiven service orchestration.

Available Toolset

• query_projects

• Function: Enumerates every service project associated with your Aiven tenancy.

• list_services_in_project

• Function: Retrieves an inventory of all managed services residing within a specified Aiven project context.

• fetch_service_specifications

• Function: Obtains comprehensive configuration details for a designated service within a given Aiven project.

• retrieve_service_attributes

• Function: Fetches supplementary metadata associated with a specific Aiven service instance. Currently optimized exclusively for Aiven for PostgreSQL® deployments.

• execute_database_statement

• Function: Permits the execution of arbitrary SQL queries against a designated Aiven for PostgreSQL® service endpoint.

Configuration for Claude Desktop Environment

1. Access the local configuration file for Claude Desktop:
2. macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows Path: %APPDATA%/Claude/claude_desktop_config.json

4. Integrate the following block into the mcpServers section:

{ "mcpServers": { "mcp-aiven-handler": { "command": "uv", "args": [ "--directory", "$REPOSITORY_DIRECTORY", "run", "--with-editable", "$REPOSITORY_DIRECTORY", "--python", "3.13", "mcp-aiven" ], "env": { "AIVEN_BASE_URL": "https://api.aiven.io", "AIVEN_PROJECT_NAME": "$DEFAULT_PROJECT_NAME", "AIVEN_TOKEN": "$AIVEN_TOKEN" } } } }

Ensure you substitute placeholder variables: * $REPOSITORY_DIRECTORY: Must resolve to the root directory of this repository. * AIVEN_PROJECT_NAME: Should be set to your standard project identifier. * AIVEN_TOKEN: Needs to be populated with a valid Aiven authentication token.

1. Locate the entry referencing the uv executable within your configuration and replace it with its fully qualified path. This guarantees the invocation of the correct uv environment. (Use which uv on Unix-like systems to find the path).

2. Relaunch Claude Desktop for the modifications to take effect.

Configuration for Cursor IDE

1. Navigate to Cursor -> Preferences -> Cursor Settings Interface.

2. Select the configuration tab labeled "MCP Servers".

3. Define a new server entry with the following parameters:

   • Identifier: mcp-aiven
   • Protocol Type: command
   • Execution String: uv --directory $REPOSITORY_DIRECTORY run --with-editable $REPOSITORY_DIRECTORY --python 3.13 mcp-aiven

Where $REPOSITORY_DIRECTORY denotes the location of the source code repository. You may also need to explicitly define AIVEN_BASE_URL, AIVEN_PROJECT_NAME, and AIVEN_TOKEN within the Cursor environment settings.

Local Development Setup

1. Populate a .env file in the repository root with the necessary secrets:

AIVEN_BASE_URL=https://api.aiven.io AIVEN_PROJECT_NAME=$DEFAULT_PROJECT_NAME AIVEN_TOKEN=$AIVEN_TOKEN

1. Install dependencies using uv sync. If uv is unavailable, refer to the installation guide here. Subsequently, activate the virtual environment: source .venv/bin/activate.

2. Initiate the MCP server for immediate testing via the command: mcp dev mcp_aiven/mcp_server.py

Required Environment Settings

The following runtime environment variables mandate configuration for the server's connection to Aiven:

Essential Variables

• AIVEN_BASE_URL: The canonical URL endpoint for the Aiven management API.
• AIVEN_PROJECT_NAME: The default project identifier to operate against.

• AIVEN_TOKEN: The bearer token required for authenticated API access.

mcp-demo

Demonstration repository utilized for validating the hosting and execution of the MCP service against Aiven infrastructure.

Cloud Computing Fundamentals (Reference)

Cloud computing is defined by the ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand." This concept is ubiquitously termed "the cloud".

== Core Characteristics == In 2011, the United States' National Institute of Standards and Technology (NIST) established five fundamental attributes defining cloud systems. These definitions are quoted precisely below:

• On-demand self-service: A user can provision computational capacities, such as processing time or network storage, independently and automatically without requiring intervention from the service provider's personnel.
• Broad network access: Services are accessible over standard network protocols, facilitating usage across diverse client platforms, including workstations, laptops, tablets, and mobile devices.
• Resource pooling: Provider infrastructure resources are aggregated to serve numerous clients simultaneously using a multi-tenant architecture, allowing dynamic allocation and reallocation of physical and virtual assets based on fluctuating demands.
• Rapid elasticity: Capabilities can be scaled up or down swiftly—sometimes autonomously—to match demand fluctuations instantly. To the consuming party, the available capacity often appears limitless.
• Measured service: Resource consumption (e.g., bandwidth, processing, storage) is automatically tracked, controlled, and optimized via metering functions implemented at an appropriate service abstraction layer. This ensures transparent reporting for both the provider and the consumer regarding usage.

By 2023, the International Organization for Standardization (ISO) had undertaken efforts to expand and refine this foundational set of characteristics.

== Historical Context ==

The genesis of cloud computing traces back to the 1960s with the emergence of time-sharing concepts, popularized through Remote Job Entry (RJE). The dominant operational model then involved centralized "data centers" where users submitted tasks to human operators managing mainframe systems. This era was characterized by pioneering efforts to democratize access to substantial computational power via time-sharing mechanisms, focusing on maximizing infrastructure, platform, and application efficiency for end-users.

The symbolic use of the "cloud" metaphor to represent virtualized services emerged in 1994. General Magic employed it to describe the interconnected 'spaces' accessible by mobile software agents operating within their Telescript environment. David Hoffman, a communications specialist at General Magic, is often credited with adapting this metaphor, which had a long history in telecommunications and networking contexts. The term "cloud computing" gained mainstream recognition in 1996 when Compaq Computer Corporation drafted a strategic business plan for future internet-based computation, articulating an ambition to supercharge...