croit/mcp-croit-ceph
If you are the rightful owner of mcp-croit-ceph and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
Model Context Protocol (MCP) server for managing croit Ceph clusters, leveraging dynamic tool generation from croit OpenAPI specifications.
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
hybrid
(default): Combines base tools with category tools for optimal balancebase_only
: Only 3 base tools for minimal footprintcategories_only
: Only category tools for simplified operationsendpoints_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 endpointscall_endpoint
- Direct API calls to any endpointget_schema
- Resolve schema references
Category Tools (top 10):
manage_services
- Ceph services operationsmanage_maintenance
- Maintenance tasksmanage_s3
- S3 bucket managementmanage_pools
- Storage pool operationsmanage_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 endpointscall_api_endpoint
- Make API callsget_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:
- Automatic Role Detection: Fetches roles via
/auth/token-info
endpoint - 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 managementconfig
,hooks
,change-requests
- Configuration changesconfig-templates
- Template management
All Other Categories are accessible to VIEWER roles for read operations:
cluster
,status
,stats
- Monitoringlogs
,disks
,services
- Information viewings3
,cephfs
,rbds
,pools
- Storage infoauthentication
,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.