Cycloid MCP

Cycloid MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the Cycloid platform, enabling AI assistants to interact with Cycloid's infrastructure management capabilities through natural language.

Overview

The Cycloid MCP Server bridges the gap between AI assistants and Cycloid's powerful infrastructure automation platform. It enables users to:

• Discover and explore available blueprints and service catalogs
• Create and manage infrastructure stacks using Cycloid's blueprints
• Interact naturally with complex infrastructure workflows through AI assistants
• Leverage Cycloid's expertise in infrastructure as code and automation

Available Tools

• `CYCLOID_BLUEPRINT_LIST`: List all available blueprints with their details
• `CYCLOID_BLUEPRINT_STACK_CREATE`: Create stacks from blueprints with interactive elicitation
• `CYCLOID_STACKFORMS_VALIDATE`: Validate StackForms configuration files
• `CYCLOID_CATALOG_REPO_LIST`: List service catalog repositories
• `CYCLOID_EVENT_LIST`: List organization events with optional filters (begin, end, severity, type)
• `CYCLOID_PIPELINE_LIST`: List all pipelines from Cycloid

Available Resources

• `cycloid://blueprints`: Access to blueprint information
• `cycloid://service-catalogs-repositories`: Access to service catalog repositories information
• `cycloid://events`: Access to recent organization events as JSON
• `cycloid://pipelines`: Access to pipeline information

Event Filters

• begin/end: Unix timestamps (strings) delimiting the time window
• severity: One or more of info, warn, err, crit
• type: One or more of Cycloid, AWS, Monitoring, Custom

Architecture

The server uses a dynamic component registration system based on FastMCP's MCPMixin:

• Automatic Discovery: Components are automatically discovered from src/components/
• File-based Organization: Components are organized by feature (catalogs/, stacks/)
• Standard Patterns: Each component follows the pattern *_tools.py, *_resources.py, *_handlers.py, *_prompts.py
• MCPMixin Integration: Uses FastMCP's built-in register_all() method for proper tool/resource registration

HTTP Transport

The Cycloid MCP Server runs as a web service using HTTP transport. Organization and API key are provided via HTTP headers (X-CY-ORG and X-CY-API-KEY) for each request, enabling multi-tenant usage.

Usage: python server.py

Quick Start

Prerequisites

• Python 3.12 or higher
• uv package manager (recommended)
• Docker (for production deployment)
• Valid Cycloid API credentials

Development Setup

# Clone and setup

git clone cd cycloid-mcp-server make setup

Run development server

make dev-server

Production Setup

Using Pre-built Docker Images

The project provides pre-built Docker images via Docker Hub:

# Pull the latest image

docker pull cycloid/cycloid-mcp-server:latest

Run the server

docker run -p 8010:8010 cycloid/cycloid-mcp-server:latest

Building Locally

# Build Docker image

make build

Run production server

make prod-server

MCP Configuration

For detailed MCP server configuration examples, see mcp-examples.md.

Available Commands

# Development Environment

make setup # Setup development environment with uv make install # Install dependencies make help # Show all available commands make validate-env # Validate local environment matches CI

Development Server

make dev-server # Run development server using Python virtual environment

HTTP Server

python server.py # Run HTTP server

Production

make build # Build Docker image make prod-server # Run production server using Docker

Testing and Quality

make test # Run all tests make type-check # Run pyright type checking make lint # Run PEP 8 linting with flake8 make format # Format code with black and isort make quality-check # Run all quality checks (tests + type checking + linting) make simulate-ci # Validate environment and run quality checks

Cleanup

make clean # Clean up development artifacts make clean-docker # Clean up Docker artifacts

Contributing

See CONTRIBUTING.md for detailed development guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.