beginner⏱️ 14-24 minutes📅 Updated June 2026

Step-by-step guide to integrate Aiven MCP server with mcp-use. Includes list_projects and list_services.

Aiven + mcp-use: Complete MCP Integration

Aiven is a MCP server that Navigate your Aiven projects and interact with the PostgreSQL®, Apache Kafka®, ClickHouse® and OpenSearch® services.

When integrated with mcp-use, you can:

  • List all projects in your Aiven account
  • List all services in a specific project
  • Get detailed information about a specific service

This guide provides step-by-step instructions to set up Aiven in mcp-use, including configuration, examples, and troubleshooting.

What You'll Achieve

After completing this setup:

  • Aiven will be fully integrated and operational
  • You can use Aiven tools directly in mcp-use
  • All Aiven capabilities will be available for your workflows
  • Access to 5 different tools

Prerequisites

Before starting, ensure you have:

  • Aiven API token with appropriate permissions
  • mcp-use installed and configured
  • Compatible operating system (Python 3.8+, Node.js 16+, pip Installation, npm/yarn Installation)

Installation

Step 1: Install Aiven

Configuration

Step 2: Configure mcp-use

  1. Open mcp-use settings
  2. Navigate to MCP server configuration
  3. Add Aiven server with appropriate settings
  4. Save and restart if needed

Examples

Once configured, you can use Aiven in mcp-use:

Multi-Cloud Database Management

undefined

Ask mcp-use: "Check status of all PostgreSQL services and their performance"

Expected Result: undefined

Event Streaming Monitoring

undefined

Ask mcp-use: "Show Kafka service health and recent message volumes"

Expected Result: undefined

Analytics Platform Health Check

undefined

Ask mcp-use: "Check ClickHouse query performance and storage usage"

Expected Result: undefined

Testing Your Setup

  1. Launch mcp-use
  2. Verify Aiven is available in the tools list
  3. Test basic Aiven functionality

Troubleshooting

Common Issues

Connection Refused or Server Unreachable

Symptoms: ECONNREFUSED error, Connection timeout, Cannot reach server

Cause: MCP server not running or incorrect URL

Solution:

  • Verify MCP server is running and accessible
  • Check server URL is correct (protocol, host, port, path)
  • Test server URL in browser or with curl to confirm it responds
  • Ensure firewall allows connections to server port
  • Verify CORS settings if accessing from browser

Import Errors or Module Not Found

Symptoms: ModuleNotFoundError: mcp_use, Cannot find module "mcp-use"

Cause: Package not installed or wrong environment

Solution:

  • Verify installation: pip show mcp-use (Python) or npm list mcp-use (JS)
  • Ensure using correct Python virtual environment or Node.js project
  • Reinstall package: pip install --upgrade mcp-use or npm install mcp-use
  • Check package.json or requirements.txt includes mcp-use

Tool Discovery Returns Empty List

Symptoms: list_tools() returns [], No tools available, Tools not found

Cause: MCP server not properly configured or not exposing tools

Solution:

  • Verify MCP server is properly initialized and configured
  • Check server logs to confirm tools are registered
  • Test server directly with MCP inspector or test client
  • Ensure server implements MCP protocol correctly
  • Verify transport type (HTTP/SSE) matches server configuration

Tool Execution Fails or Returns Errors

Symptoms: Tool call throws exception, Invalid arguments error, Execution timeout

Cause: Incorrect arguments or server-side execution failure

Solution:

  • Verify tool arguments match schema definition from list_tools()
  • Check required arguments are provided with correct types
  • Review server logs for detailed error messages
  • Test tool with minimal valid arguments first
  • Increase timeout if tool requires longer execution time

LangChain.js Integration Not Working

Symptoms: getLangChainTools() fails, Tools not recognized by agent, Type errors

Cause: Version mismatch or incorrect integration setup

Solution:

  • Ensure LangChain.js version is compatible with mcp-use
  • Verify TypeScript version meets requirements
  • Check tool schema conversion is working correctly
  • Use latest versions of both mcp-use and LangChain.js
  • Review LangChain.js documentation for agent setup

Transport Type Errors (HTTP vs SSE)

Symptoms: SSE connection fails, HTTP polling not working, Event stream errors

Cause: Mismatch between client transport and server capabilities

Solution:

  • Verify server supports the transport type you are using
  • Try alternative transport: switch between "http" and "sse"
  • Check server documentation for supported transport types
  • For SSE, ensure server sends proper Content-Type: text/event-stream
  • For HTTP, verify server accepts POST requests with JSON payload

Aiven not appearing in mcp-use

Symptoms: Server not listed, Tools not available

Cause: Configuration or installation issue

Solution:

  • Verify configuration syntax
  • Check Aiven installation
  • Restart mcp-use
  • Check logs for error messages

Next Steps

Now that Aiven is integrated with mcp-use:

  • Explore all Aiven capabilities through mcp-use
  • Check out other MCP servers that work with mcp-use
  • Join the MCP community for tips and support
  • Consider contributing to Aiven development

Need Help?

Related Resources

More Integrations

Explore other MCP servers that work with mcp-use

Need Help?

Join the MCP community for support and discussions

Aiven + mcp-use: MCP Setup Guide (2026)