realm9-ai-agent

The Realm9 AI Agent System includes three core components: an AI Terraform Code Editor, the MCP (Model Context Protocol) Server, and a Kubernetes Observability Agent. The MCP server exposes 45+ standardized tools for infrastructure management, including database queries, file and Terraform operations, execution and monitoring, and broader infrastructure tasks. This enables an AI agent to discover, call, and compose these tools through a consistent interface without needing direct access to underlying systems. To use it, deploy the MCP server within your environment and connect your LLM-driven agents to query and invoke tools via the MCP API. The system supports multi-tenant isolation with Redis-backed session state and PostgreSQL for registrations and configurations, ensuring secure, auditable interactions. You can leverage the MCP tools to perform Terraform plan/apply workflows, view Git status, manage Terraform files, validate configurations, and execute deployment and monitoring tasks across your infrastructure. The Kubernetes Observability Agent complements this by deploying OpenTelemetry collectors in user clusters, forwarding telemetry to Realm9 observability services, and reporting health and configuration updates back to the MCP-enabled control plane.

Prerequisites:

• Node.js 18+ and npm (for npx-based deployment)
• Access to Redis and PostgreSQL (or compatible equivalents) for state and registration data
• Network access to pull MCP server package from npm or your registry

Installation steps:

1. Install prerequisites and verify environment

   • Check Node.js version: node -v
   • Check npm version: npm -v

2. Run the MCP server with npx (no local installation required)

   • npx -y realm9-ai-agent

3. Alternative: install locally and run directly

   • npm install -g realm9-ai-agent
   • realm9-ai-agent

4. Configure environment variables (example)

   • Create a .env file or export variables in your shell: MCP_ROLE=server REDIS_URL=redis://localhost:6379 POSTGRES_URL=postgres://user:pass@localhost:5432/realm9 API_KEYS=your-llm-provider-keys

5. Validate installation

   • Ensure MCP server logs indicate it is discovering and exposing tools
   • Confirm connectivity from your LLM to the MCP endpoint and tool discovery works

6. Optional: run with Docker (if preferred)

   • docker run -i realm9-ai-agent:latest

Notes:

• The MCP server is designed to run alongside your existing infrastructure and UI components. Adjust the storage and authentication components to fit your security requirements.

Tips and common issues:

• Ensure Redis TTL settings are tuned to your workload to avoid stale state leaking between sessions.
• Use PostgreSQL back-end for reliable registrations and observability configurations.
• When integrating with multiple LLM providers, populate API_KEYS with appropriate credentials and manage quotas to avoid overage.
• If tool discovery fails, verify network access to the MCP endpoint and that the MCP package name matches the published artifact in your registry.
• For multi-tenant deployments, enforce organization scoping at the LLM level and through MCP filtering rules.
• If you upgrade MCP tools, ensure backwards compatibility in your agent configurations to prevent breaking changes in tool signatures.
• Review GitOps integration settings to ensure your Terraform changes are committed with meaningful messages.