Quick Start
Option 1: Remote (hosted by Aiven)
The MCP server is hosted at https://mcp.aiven.live/mcp. Your MCP client will prompt you to authorize on Aiven.
Claude Code
claude mcp add --scope user --transport http aiven-mcp "https://mcp.aiven.live/mcp"
Cursor
Or manually add to Cursor MCP settings:
{
"mcpServers": {
"aiven-mcp": {
"url": "https://mcp.aiven.live/mcp"
}
}
}
VS Code / Copilot
Add to .vscode/mcp.json in your workspace:
{
"servers": {
"aiven-mcp": {
"type": "http",
"url": "https://mcp.aiven.live/mcp"
}
}
}
Read-Only Mode (Remote)
Enable read-only mode by adding ?read_only=true to the URL. All write operations will be excluded from the MCP:
{
"mcpServers": {
"aiven-mcp": {
"url": "https://mcp.aiven.live/mcp?read_only=true"
}
}
}
Scoped Tools (Remote)
Reduce the tool surface exposed to your AI agent by adding ?services_scope= to the URL. Useful when you only work with a subset of Aiven services and want to keep the agent's context focused. Combine values with commas. core (project/service discovery) is always included implicitly.
Valid scopes: all, core, pg, kafka, application, integrations, opensearch. Use all to explicitly load every tool (same as omitting the param). all cannot be combined with other scopes. opensearch follows the same rules as kafka or pg (core plus OpenSearch-category tools); there are no OpenSearch-specific tools yet, so it currently exposes core only.
{
"mcpServers": {
"aiven-mcp": {
"url": "https://mcp.aiven.live/mcp?services_scope=kafka"
}
}
}
You can also combine with read_only:
https://mcp.aiven.live/mcp?services_scope=pg&read_only=true
Write Exceptions in Read-Only Mode (Remote)
When read_only=true, add ?write_allowlist= to re-enable specific write tools while keeping
everything else read-only. Useful when you want mostly-read access but still need to allow one
write action, for example creating Kafka topics. Combine multiple tool names with commas. Ignored
when read_only is not enabled.
https://mcp.aiven.live/mcp?read_only=true&write_allowlist=aiven_kafka_topic_create
Marketplace Customers (Remote)
If you subscribed to Aiven through a cloud marketplace, add your marketplace as a path segment so sign-in uses the correct console:
| Marketplace | Path segment |
|---|
| AWS Marketplace | https://mcp.aiven.live/mcp/aws |
| Azure Marketplace | https://mcp.aiven.live/mcp/azure |
| Google Cloud Marketplace | https://mcp.aiven.live/mcp/gcp |
{
"mcpServers": {
"aiven-mcp": {
"url": "https://mcp.aiven.live/mcp/<marketplace>"
}
}
}
The path segment combines with the query parameters above, for example https://mcp.aiven.live/mcp/gcp?services_scope=pg&read_only=true.
Option 2: stdio (local)
Run the server locally as a child process of your MCP client. Requires Node.js 18+.
You must provide your Aiven API token via the AIVEN_TOKEN environment variable. Create a token here.
Claude Code
claude mcp add --scope user aiven-mcp -e AIVEN_TOKEN=your-token-here -- npx -y mcp-aiven
Cursor, VS Code -- add to your MCP client config:
{
"mcpServers": {
"aiven-mcp": {
"command": "npx",
"args": ["-y", "mcp-aiven"],
"env": {
"AIVEN_TOKEN": "your-token-here"
}
}
}
}
Config file locations:
- Cursor: Cursor Settings > MCP Servers
- VS Code:
.vscode/mcp.json in your workspace
Option 3: Local development
Run a local build of the server (useful for development and testing):
pnpm install && pnpm generate:api-types && pnpm generate && pnpm build && AIVEN_TOKEN="<YOUR_TOKEN>" MCP_TRANSPORT="http" PORT=3000 node dist/index.js
The server listens on port 3000 by default. Connect your MCP client to http://localhost:3000/mcp.
To point a remote deployment at a custom host (e.g. your local build), set MCP_HOST:
MCP_HOST=http://localhost:3000 node dist/index.js
Environment Variables
| Variable | Required | Default | Description |
|---|
AIVEN_TOKEN | stdio only | -- | Aiven API token (create one here) |
AIVEN_READ_ONLY | No | false | Set to true to expose only read-only tools |
AIVEN_SERVICES_SCOPE | No | -- | Comma-separated scopes to expose (e.g. kafka, pg,kafka, or all). Valid: all, core, pg, kafka, application, integrations, opensearch. core is included implicitly for scoped service types. opensearch has no dedicated tools yet (core only until OpenSearch tools are added). Omitting the var or setting all loads every tool. |
AIVEN_ALLOW_SECRETS | No | false | Set to true to expose the aiven_service_connection_info tool, which returns live credentials (passwords, connection URIs, certs) into the conversation. Disabled while AIVEN_READ_ONLY=true. |
AIVEN_WRITE_ALLOWLIST | No | -- | Comma-separated tool names to re-enable while AIVEN_READ_ONLY=true (e.g. aiven_kafka_topic_create). Ignored when read-only mode is not enabled. |
MCP_HOST | No | https://mcp.aiven.live | Override the OAuth protected resource host |
MCP_TRANSPORT | No | stdio | Set to http to start an HTTP server instead of stdio |
MCP_HTTP_RATE_LIMIT_MAX | No | 1000 | Max requests per window on POST /mcp (HTTP transport), per bearer token. Client IP rate limiting is expected at Cloudflare. |
MCP_HTTP_RATE_LIMIT_WINDOW_MS | No | 60000 | Window length in milliseconds for MCP_HTTP_RATE_LIMIT_MAX. |
EXTRA_PROTECTION | No | false | Set to true on HTTP deployments to require a valid X-Edge-Auth header on every request except GET /health. See Edge protection rollout below. |
MCP_EDGE_AUTH_SECRET | When EXTRA_PROTECTION=true | -- | Shared secret; must match the value Cloudflare injects as X-Edge-Auth via Transform Rules. |
In remote (HTTP) mode, AIVEN_TOKEN is not needed. Your MCP client sends your token as a Bearer token with each request.
Production HTTP traffic is rate-limited in two layers: Cloudflare enforces a per-client-IP limit (configured in the Cloudflare dashboard), and this server enforces MCP_HTTP_RATE_LIMIT_* per bearer token on POST /mcp.
Edge protection rollout
When EXTRA_PROTECTION=true, any mismatch between MCP_EDGE_AUTH_SECRET and the value Cloudflare injects as X-Edge-Auth causes every request to return 403 (except GET /health). Both values are environment/config on opposite sides of the wire, so the only recovery path is to fix the secret and redeploy or update Cloudflare.
Enable in this order:
- Cloudflare Transform Rule — Add a rule that sets
X-Edge-Auth (and, if used for PG tools, X-Client-IP) on traffic to the MCP origin. Note the secret value you configure.
MCP_EDGE_AUTH_SECRET — Deploy the server with this env var set to the same secret as the Transform Rule. Leave EXTRA_PROTECTION unset or false for now; verify the origin still accepts traffic.
EXTRA_PROTECTION=true — Enable only after steps 1–2 are live and matched. Confirm a normal MCP request succeeds and direct origin access without X-Edge-Auth is rejected.
- Secret rotation — Update Cloudflare and
MCP_EDGE_AUTH_SECRET together (or briefly set EXTRA_PROTECTION=false), redeploy, then re-enable. Never rotate one side alone while the flag is on.
If EXTRA_PROTECTION=true at startup and MCP_EDGE_AUTH_SECRET is missing, the process exits immediately with an error.
While rejections continue, the server logs a misconfig warning at most once every 15 minutes (reset after a request with valid X-Edge-Auth), so a secret mismatch is visible in logs without one line per rejected request.