MCP Croit Ceph

You can connect an AI assistant to your Croit Ceph cluster through an MCP server that exposes the cluster’s REST API. This enables natural language queries to inspect health, list resources, search logs, and perform management tasks with intelligent data handling and optimized responses.

How to use

Use an MCP client to connect to the Croit Ceph MCP server. You can ask questions like the cluster health status, which pools are near full, which OSDs are experiencing issues, or to search logs for specific events. The server supports token-optimized responses, field selections to reduce data transfer, and smart summaries for large results. When you ask for data, the AI will fetch only what you request and provide drill-down details as needed. You can also leverage built-in log analysis and RBAC controls to ensure secure access.

How to install

Prerequisites: ensure Docker is installed on your machine or server where you will run the MCP container.

Run the MCP server using Docker as shown in the quick start example. This starts the MCP server container with your cluster URL and API token. Replace the environment values with your actual cluster URL and API token.

docker run --rm -i \
  -e CROIT_HOST="https://your-cluster.com" \
  -e CROIT_API_TOKEN="your-api-token" \
  croit/mcp-croit-ceph:latest

Configuration and usage notes

Configure your client with the necessary environment variables to connect to your Croit Ceph cluster. You can adjust logging and startup behavior using additional environment variables if needed.

Basic environment variables from the example configuration include CROIT_HOST for the cluster URL and CROIT_API_TOKEN for authentication. Optional variables like LOG_LEVEL can be used to control verbosity.

# Basic environment setup for the MCP container
CROIT_HOST="https://your-cluster.com"
CROIT_API_TOKEN="your-api-token"

Security and access

Access is controlled by the API token’s role. ADMIN tokens grant full access, while VIEWER tokens provide read-only operations. Ensure tokens have the appropriate permissions for the tasks you intend to perform.

If you enable additional logging or debug modes, use them temporarily for troubleshooting and disable when not needed to reduce noise and potential exposure of sensitive data.

Troubleshooting

If the container cannot reach your cluster, verify CROIT_HOST is correct and that network connectivity allows outbound access to the cluster. Ensure the API token is valid and has the required permissions. Check that Docker is running and the container has appropriate resources.

If there are tool visibility issues, review the startup logs for errors related to endpoint discovery or OpenAPI specification validation. You can also restart with a debug log level to gather more details.

Examples of typical usage

Check cluster health: You ask, and the AI returns a health summary with optional drill-down to endpoints or specific components.

List pools with issues: You request pools with errors, and the AI fetches the relevant fields (id, name, status) and filters to show only those with problems.

Search logs for a time window: You say you want OSD failures in the last hour, and the AI uses log search tooling to summarize and drill into details.

Advanced usage

You can supply a local OpenAPI spec for faster startup and offline development. If you have a local spec at /config/openapi.json, you can mount it into the container and set OPENAPI_FILE to speed startup.

To enable verbose debugging, set LOG_LEVEL to DEBUG when starting the container.

Notes

Restart the MCP client after changing configuration to ensure new settings take effect.

API tokens and permissions

1. Log into your Croit cluster web interface. 2. Go to Settings → API Tokens. 3. Create a new token with the required permissions. 4. Use the token in your MCP configuration.

Available tools

list_endpoints

Discover available API endpoints on the MCP server.

call_endpoint

Make optimized API calls to fetch or manipulate cluster data.

search_last_result

Drill down into large responses to extract relevant items.

croit_log_search

Advanced log analysis and natural language search across logs.

croit_log_check

Quick checks for log-based conditions.

manage_services

Ceph services management.

manage_pools

Ceph storage pools management.

manage_servers

Cluster servers management.

manage_s3

S3 buckets management.