Skip to main content
Glama

MCP Croit Ceph

Official
by croit
GitHub
Python
MIT License
1
  • Linux
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

MCP Croit Ceph

An MCP (Model Context Protocol) server for interacting with Croit Ceph clusters through their REST API.

Current Status

  • 580 total API endpoints

  • 575 endpoints with x-llm-hints (99.1% coverage)

  • 100% endpoints have summaries

  • 13 tools in hybrid mode (97% reduction)

  • Full support for all x-llm-hints fields

Features

Automatic Token Optimization

The MCP server automatically optimizes responses to reduce token consumption:

  • Auto-limits: Adds default limits (10-100 items) to list operations

  • Smart truncation: Large responses automatically truncated with metadata

  • Optimization hints: Tool descriptions include token-saving tips

  • Response metadata: Truncated responses include info on how to get more data

Example: Instead of 500 services (50,000 tokens), you get 25 services + metadata (2,500 tokens)

Built-in Filtering (grep-like search)

Filter API responses locally without multiple calls:

  • Field filtering: _filter_status='error' - exact match

  • Regex patterns: _filter_name='~ceph.*' - pattern matching

  • Numeric comparisons: _filter_size='>1000' - greater than

  • Text search: _filter__text='timeout' - search all text fields

  • Field existence: _filter__has='error_message' - has field

  • Multiple values: _filter_status=['error','warning'] - OR logic

Example: Find errors in 500 services with one call:

_filter_status='error' → Returns only 5 error services (99% token savings)

Hybrid Mode (Default) - 97% Fewer Tools!

The new hybrid mode reduces the tool count from 580 individual endpoint tools to just 13 tools total:

  • 3 Base tools for full API access

  • 10 Category tools for common operations (services, maintenance, s3, pools, etc.)

This dramatic reduction improves:

  • LLM performance and response times

  • Tool discovery and usability

  • Memory efficiency

  • Startup time

Tool Generation Modes

  1. hybrid (default): Combines base tools with category tools for optimal balance

  2. base_only: Only 3 base tools for minimal footprint

  3. categories_only: Only category tools for simplified operations

  4. endpoints_as_tools: Legacy mode with 580 individual tools (one per API endpoint)

Dynamic Features

  • Automatic API Discovery: Fetches OpenAPI spec from your Croit cluster

  • Permission-Based Filtering: Role-based tool filtering (ADMIN vs VIEWER)

  • Full x-llm-hints Support: 575+ endpoints with AI optimization hints

  • Local OpenAPI Support: Use a local OpenAPI spec file for testing/development

  • Schema Resolution: Handles $ref references automatically

Advanced x-llm-hints Integration

The MCP server fully integrates Croit's x-llm-hints into tool descriptions for optimal LLM guidance:

What x-llm-hints provide:

  • Purpose: Clear description of what each endpoint does

  • Usage examples: Common use cases and workflow guidance

  • Failure modes: Expected errors and how to handle them

  • Rate limits: API throttling information for efficient usage

  • Retry strategies: How to handle transient failures

  • Poll intervals: Recommended refresh rates for live data

  • Cache hints: Response caching strategies

  • Related endpoints: Cross-references for complex workflows

Examples of integrated hints:

manage_cluster tool: Purpose: Bootstrap a brand-new Ceph cluster using the selected MON disk and IP address. Common usage: • Invoke immediately after fetching candidates from GET /cluster/create/mons • Monitor the returned ManagedTask via /tasks/{id} until bootstrap completes Failure modes: • 400: Validate disk/server eligibility via GET /cluster/create/mons • 409: If concurrent bootstrap is in progress, wait for existing task Rate limits: 60/300s, 30/300s Retry strategy: manual_retry, exponential_backoff

Benefits for LLMs:

  • Context-aware operations: LLMs understand when and how to use each tool

  • Error handling: Proactive guidance on handling API errors

  • Performance optimization: Built-in rate limiting and caching awareness

  • Workflow intelligence: Understanding of multi-step operations

Installation

⚠️ IMPORTANT: This project requires a virtual environment due to system-managed Python environments.

# Clone the repository git clone https://github.com/croit/mcp-croit-ceph.git cd mcp-croit-ceph # Create and activate virtual environment (REQUIRED) python3 -m venv venv source venv/bin/activate # Linux/Mac # or: venv\Scripts\activate # Windows # Install dependencies in virtual environment pip install -r requirements.txt

Note: Always activate the virtual environment (source venv/bin/activate) before running any Python commands or tests.

Configuration

Set up your environment variables:

export CROIT_HOST="https://your-croit-cluster.com" export CROIT_API_TOKEN="your-api-token"

Or use a config file at /config/config.json:

{ "host": "https://your-croit-cluster.com", "api_token": "your-api-token" }

Usage

Basic Usage (Hybrid Mode)

# Activate virtual environment first (REQUIRED) source venv/bin/activate # Default hybrid mode with permission checking python mcp-croit-ceph.py

Advanced Options

# Activate virtual environment first (REQUIRED) source venv/bin/activate # Use local OpenAPI spec file python mcp-croit-ceph.py --openapi-file openapi.json # Skip permission checking (faster startup) python mcp-croit-ceph.py --no-permission-check # Use only base tools (minimal mode) python mcp-croit-ceph.py --mode base_only # Use only category tools python mcp-croit-ceph.py --mode categories_only # Legacy mode with all 580 endpoint tools (not recommended) python mcp-croit-ceph.py --mode endpoints_as_tools # Customize category tool limits python mcp-croit-ceph.py --max-category-tools 5

Tool Modes Explained

Hybrid Mode (Recommended)

Provides the best balance with ~13 tools:

Base Tools:

  • list_endpoints - Search and filter API endpoints

  • call_endpoint - Direct API calls to any endpoint

  • get_schema - Resolve schema references

Category Tools (top 10):

  • manage_services - Ceph services operations

  • manage_maintenance - Maintenance tasks

  • manage_s3 - S3 bucket management

  • manage_pools - Storage pool operations

  • manage_servers - Server management

  • And more...

Each category tool supports actions like: list, get, create, update, delete

Base Only Mode

Minimal setup with just 3 tools for full API access:

  • list_api_endpoints - Discover available endpoints

  • call_api_endpoint - Make API calls

  • get_reference_schema - Resolve schemas

Categories Only Mode

Simplified interface with only category tools, no base tools.

Endpoints as Tools Mode (Legacy)

Creates 580 individual tools (one per API endpoint). Not recommended due to:

  • Performance overhead

  • Difficult tool discovery

  • MCP client limitations

Permission-Based Filtering

The server intelligently filters tools based on the API token's role:

  1. Automatic Role Detection: Fetches roles via /auth/token-info endpoint

  2. Role-Based Access:

    • ADMIN role: Full access to all categories

    • VIEWER/other roles: All categories except admin-only operations

    • Invalid token: Server will exit with error (no access)

Category Access Control

Admin-Only Categories:

  • maintenance, servers, ipmi - System management

  • config, hooks, change-requests - Configuration changes

  • config-templates - Template management

All Other Categories are accessible to VIEWER roles for read operations:

  • cluster, status, stats - Monitoring

  • logs, disks, services - Information viewing

  • s3, cephfs, rbds, pools - Storage info

  • authentication, images, daos - Read operations

  • And all others not listed as admin-only

This role-based approach is fast and ensures users only see tools they can actually use.

Using Local OpenAPI Spec

For offline development or testing:

# Download spec from your cluster curl -H "Authorization: Bearer $CROIT_API_TOKEN" \ https://your-cluster/api/swagger.json > openapi.json # Use the local file python mcp-croit-ceph.py --openapi-file openapi.json

MCP Integration

With Claude Desktop

Add to your Claude Desktop config:

{ "mcpServers": { "croit-ceph": { "command": "python", "args": ["/path/to/mcp-croit-ceph.py"], "env": { "CROIT_HOST": "https://your-cluster", "CROIT_API_TOKEN": "your-token" } } } }

With Other MCP Clients

The server implements the standard MCP protocol and works with any compatible client.

Command Line Arguments

Argument

Description

Default

--mode

Tool generation mode

hybrid

--openapi-file

Local OpenAPI spec file

None (fetch from server)

--no-permission-check

Skip permission checking

False (check enabled)

--max-category-tools

Max category tools to generate

10

--no-resolve-references

Don't resolve $ref in spec

False (resolve enabled)

--offer-whole-spec

Include full spec in list tool

False

Docker Usage

Build and Run with Docker

# Build the Docker image docker build -t mcp-croit-ceph . # Run with environment variables docker run -it --rm \ -e CROIT_HOST="https://your-cluster" \ -e CROIT_API_TOKEN="your-token" \ mcp-croit-ceph # Run with local OpenAPI spec (for testing) docker run -it --rm \ -v $(pwd)/openapi.json:/config/openapi.json:ro \ -e CROIT_HOST="http://dummy" \ -e CROIT_API_TOKEN="dummy" \ mcp-croit-ceph \ --mode hybrid --openapi-file /config/openapi.json --no-permission-check

Docker Compose

version: '3.8' services: mcp-croit-ceph: image: mcp-croit-ceph:latest environment: CROIT_HOST: "${CROIT_HOST}" CROIT_API_TOKEN: "${CROIT_API_TOKEN}" MCP_ARGS: "--mode hybrid" volumes: # Optional: Use local OpenAPI spec - ./openapi.json:/config/openapi.json:ro

Development

⚠️ Remember: Always activate the virtual environment before development work:

source venv/bin/activate

Testing Tool Count

# Activate virtual environment first source venv/bin/activate # Check how many tools will be generated in each mode for mode in hybrid base_only categories_only; do echo "$mode: $(python mcp-croit-ceph.py --mode $mode --openapi-file openapi.json --no-permission-check 2>&1 | grep -o 'Generated [0-9]* tools')" done

Debug Logging

# Activate virtual environment first source venv/bin/activate # Enable debug logging export LOG_LEVEL=DEBUG python mcp-croit-ceph.py

Testing with Local OpenAPI Spec

# Activate virtual environment first source venv/bin/activate # Use the test script ./test-local.sh # Or manually test different modes python mcp-croit-ceph.py --mode hybrid --openapi-file openapi.json --no-permission-check

Running Tests

# Activate virtual environment first source venv/bin/activate # Run timestamp fix test python test_timestamp_fix.py # Run other tests (ensure dependencies are installed in venv) python test_actual_mcp.py

License

Apache 2.0

Support

For issues specific to this MCP server, please open an issue in this repository. For Croit-specific questions, contact Croit support.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables interaction with Croit Ceph clusters through their REST API with 580 endpoints, automatic token optimization, built-in filtering, and role-based access control. Features hybrid mode tools that reduce complexity while providing full cluster management capabilities.

  1. Current Status
    1. Features
      1. Automatic Token Optimization
      2. Built-in Filtering (grep-like search)
      3. Hybrid Mode (Default) - 97% Fewer Tools!
      4. Tool Generation Modes
      5. Dynamic Features
      6. Advanced x-llm-hints Integration
    2. Installation
      1. Configuration
        1. Usage
          1. Basic Usage (Hybrid Mode)
          2. Advanced Options
        2. Tool Modes Explained
          1. Hybrid Mode (Recommended)
          2. Base Only Mode
          3. Categories Only Mode
          4. Endpoints as Tools Mode (Legacy)
        3. Permission-Based Filtering
          1. Category Access Control
        4. Using Local OpenAPI Spec
          1. MCP Integration
            1. With Claude Desktop
            2. With Other MCP Clients
          2. Command Line Arguments
            1. Docker Usage
              1. Build and Run with Docker
              2. Docker Compose
            2. Development
              1. Testing Tool Count
              2. Debug Logging
              3. Testing with Local OpenAPI Spec
              4. Running Tests
            3. License
              1. Support

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/croit/mcp-croit-ceph'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server