Cycloid

io.cycloid.mcpPublished by mcp.cycloid.ioOfficial publisherv1.0.1Updated Oct 30, 2026

An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform

VerifiedStreamable HTTPWeb executableCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

Remote MCP server for the Cycloid internal development portal, letting an assistant browse projects, environments, components, blueprints, pipelines and…

What you can do
  • List and inspect projects, their environments and components, plus organization members
  • Browse blueprints and service catalog repositories, and create a stack from a blueprint
  • Validate StackForms configuration files and get feedback on issues
  • List pipelines and organization or project-scoped events, filtered by action, entity, severity or time window
When to use it
Useful when your team runs infrastructure as code and platform engineering on Cycloid and you want an assistant to explore projects, environments and components, review recent events and pipelines, or scaffold a new stack from a blueprint.
Requirements
A remote endpoint at mcp.cycloid.io over streamable HTTP; no local install. Requires a Cycloid API key sent in the X-CY-API-KEY header and the organization canonical name in the X-CY-ORG header on each request. The README also lists Python 3.12 and Docker for self-hosting.
Before you install
The API key is a secret sent as a header on every request; keep it scoped and out of logs. The organization header selects the tenant, so a wrong value can expose another organization's data. Creating a stack from a blueprint writes to your Cycloid organization and may provision real infrastructure.

Installation

In SourceWeft

  1. Open Cycloid in the dashboard and add it to a workspace.
  2. Connect Custom headers credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.cycloid.mcp%2Fserver/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "cycloid": {
      "type": "http",
      "url": "https://mcp.cycloid.io/mcp",
      "headers": {
        "X-CY-API-KEY": "<VALUE>",
        "X-CY-ORG": "<VALUE>"
      }
    }
  }
}

README

Cycloid MCP Server

[PR Quality Check]

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

bash
# Clone and setupgit clone <repository-url>cd cycloid-mcp-servermake setup
# Run development servermake dev-server

Production Setup

Using Pre-built Docker Images

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

bash
# Pull the latest imagedocker pull cycloid/cycloid-mcp-server:latest
# Run the serverdocker run -p 8010:8010 cycloid/cycloid-mcp-server:latest
Building Locally
bash
# Build Docker imagemake build
# Run production servermake prod-server

MCP Configuration

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

Available Commands

bash
# Development Environmentmake setup          # Setup development environment with uvmake install        # Install dependenciesmake help           # Show all available commandsmake validate-env   # Validate local environment matches CI
# Development Servermake dev-server     # Run development server using Python virtual environment
# HTTP Serverpython server.py  # Run HTTP server
# Productionmake build          # Build Docker imagemake prod-server    # Run production server using Docker
# Testing and Qualitymake test           # Run all testsmake type-check     # Run pyright type checkingmake lint           # Run PEP 8 linting with flake8make format         # Format code with black and isortmake quality-check  # Run all quality checks (tests + type checking + linting)make simulate-ci    # Validate environment and run quality checks
# Cleanupmake clean          # Clean up development artifactsmake 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.

Source: README.md at commit c9cd9e8

Tools

13

CYCLOID_CATALOG_REPO_LIST

List all available service catalog repositories with their details. The LLM can filter the results based on user requirements.

Takes no parameters.

CYCLOID_COMPONENT_GET

Get the state of one or more components in a project environment.

Parametersenvrequiredprojectrequiredcanonicalsrequired

CYCLOID_COMPONENT_LIST

List components in a project environment.

Parametersenvrequiredprojectrequired

CYCLOID_EVENT_LIST

List organization events with optional filters. To filter by WHAT HAPPENED, use `action` (e.g. create, update, delete, configure, pause, unpause) and/or `entity` (e.g. component, ci_build, ci_job, pipeline, credential) — these are matched case-insensitively against each event's actual `action`/`entity` tag VALUE (note: the entity is `ci_build`, not `build`). If a filter matches nothing while events exist, the response lists the available_actions/available_entities to retry with. `type` is ONLY the high-level category: Cycloid, AWS, Monitoring, Custom (do NOT pass an action/entity name as `type`). `severity` is one of: info, warn, err, crit. `begin`/`end` are Unix timestamps in SECONDS (strings); omit any filter to include all of its values. Returns full event payload including tags. Actor identity is in tags as {key: 'user', value: '<username>'}.

Parametersendtypebeginactionentityseverity

CYCLOID_PROJECT_EVENTS

List events scoped to a specific project's components. Walks project → envs → components, then filters org-wide events by project tag. Returns events, count, and a deduplicated actors list extracted from tags[key=user]. Actor usernames can be cross-referenced with CYCLOID_MEMBER_LIST to get numeric ids for building member URLs. Hard cap: aborts with a structured error if total components exceed the configured maximum (default 50). Use begin/end/severity/type/action/entity to narrow results. Filter by WHAT HAPPENED with `action` (e.g. create, update, delete, configure, pause, unpause) and/or `entity` (e.g. component, ci_build, ci_job, pipeline) — matched case-insensitively against each event's actual tag VALUE (the entity is `ci_build`, not `build`). If a filter matches nothing while events exist, the response lists available_actions/available_entities to retry with. `type` is ONLY the high-level category: Cycloid, AWS, Monitoring, Custom (do NOT pass an action/entity name as `type`). `severity` is one of: info, warn, err, crit.

Parametersendtypebeginactionentityprojectrequiredseverity

CYCLOID_MEMBER_LIST

List all members of the organization. Use this to look up a member's numeric `id` from their `username`. The `id` field is required to build member URLs: /organizations/<org>/members/<id>.

Takes no parameters.

CYCLOID_PIPELINE_LIST

List all pipelines from Cycloid.

Takes no parameters.

CYCLOID_PROJECT_GET

Get one or more projects by canonical.

Parameterscanonicalsrequired

CYCLOID_PROJECT_LIST_ENV

List environments in a project.

Parametersprojectrequired

CYCLOID_PROJECT_LIST

List all projects in the organization.

Takes no parameters.

CYCLOID_STACKFORMS_VALIDATE

Validate a StackForms (.forms.yml) file using the Cycloid CLI. This tool can validate StackForms configuration and provide detailed feedback for fixing issues.

Parametersforms_contentrequired

CYCLOID_BLUEPRINT_STACK_CREATE

Create a new Cycloid stack from a blueprint. CRITICAL: When elicitation context (ctx) is provided, the tool will ALWAYS use interactive elicitation to ask for parameters one by one, REGARDLESS of any parameters provided. The LLM should ONLY provide the 'ref' parameter and let elicitation handle the rest. DO NOT provide name, use_case, or service_catalog_source_canonical when elicitation is available.

Parametersrefrequired

CYCLOID_BLUEPRINT_LIST

List all available blueprints with their details. The LLM can filter the results based on user requirements.

Takes no parameters.

Version history

1
  1. v1.0.1LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts