Skip to main content

Crossplane MCP Server

Create a powerful Model Context Protocol (MCP) server for Crossplane in minutes with our AI Gateway. This guide walks you through setting up seamless cloud infrastructure management integration with enterprise-grade security and instant API authentication.

About Crossplane API​

Crossplane is an open-source CNCF project that extends Kubernetes to build control planes for cloud infrastructure and services. It enables platform teams to define custom APIs (Composite Resources) that abstract and compose managed infrastructure resources, providing a unified control plane for multi-cloud operations.

Key Capabilities​

  • Composite Resource Definitions (XRDs): Define custom Kubernetes APIs that abstract infrastructure complexity
  • Compositions: Declarative infrastructure templates that map custom APIs to managed resources
  • Provider Packages: Install cloud provider integrations (AWS, Azure, GCP, and more)
  • Function Packages: Advanced composition logic with reusable transformation functions
  • Configuration Packages: Portable platform definitions for sharing and distribution
  • Environment Configs: Shared data injection into compositions for cross-resource configuration
  • Resource Protection: Usage tracking to prevent accidental deletion of dependent resources
  • Operations Scheduling: Automated infrastructure operations with cron-based and watch-based triggers

API Features​

  • Kubernetes-Native API: Standard Kubernetes resource model with custom resource definitions
  • Declarative Management: Infrastructure defined as Kubernetes manifests
  • Package System: Versioned, distributable packages with revision history and rollback
  • Composition Engine: Template-based resource composition with patching and transforms
  • Runtime Configuration: Customizable provider deployment settings
  • Resource Protection: Dependency tracking across cluster and namespace scopes

What You Can Do with Crossplane MCP Server​

The MCP server transforms Crossplane's API into a natural language interface, enabling AI agents to:

Composite Resource Management​

  • XRD Operations

    • "List all CompositeResourceDefinitions in the cluster"
    • "Create a new XRD for a managed database abstraction"
    • "Get the status and schema of the network-fabric XRD"
    • "Update the XRD to add a new configurable field for backup retention"

  • Composition Management

    • "List all Compositions and their target XRD references"
    • "Create a Composition that maps a database claim to an RDS instance and security group"
    • "Get the details of the production-tier Composition for compute resources"
    • "Show all CompositionRevisions for the storage Composition"

  • Environment Configuration

    • "List all EnvironmentConfigs in the cluster"
    • "Create an EnvironmentConfig with shared networking parameters"
    • "Update the staging EnvironmentConfig with new VPC settings"
    • "Delete the deprecated test EnvironmentConfig"

Package Management​

  • Provider Operations

    • "List all installed Providers and their health status"
    • "Install the AWS provider at version 1.5.0"
    • "Get the details of the Azure provider including its installed CRDs"
    • "Show all ProviderRevisions and their active/inactive status"

  • Configuration Packages

    • "List all installed Configuration packages"
    • "Install the platform-ref-aws Configuration for a reference platform"
    • "Get the revision history for the networking Configuration"
    • "Roll back the database Configuration to the previous revision"

  • Function Packages

    • "List all installed composition Functions"
    • "Install the function-patch-and-transform Function"
    • "Get the details and version of the auto-ready Function"
    • "Show the FunctionRevisions for the Go templating Function"

Operations & Automation​

  • Operation Management

    • "List all active Operations in the cluster"
    • "Create an Operation to trigger a database backup"
    • "Get the status and result of the infrastructure migration Operation"
    • "Delete the completed cleanup Operation"

  • Scheduled Operations

    • "List all CronOperations and their schedules"
    • "Create a CronOperation for nightly database snapshots"
    • "Update the backup CronOperation schedule to run every 6 hours"
    • "Delete the deprecated weekly cleanup CronOperation"

  • Watch-Based Operations

    • "List all WatchOperations monitoring cluster resources"
    • "Create a WatchOperation to trigger scaling on resource utilization changes"
    • "Get the configuration of the auto-remediation WatchOperation"
    • "Update the WatchOperation to watch for additional resource types"

Resource Protection​

  • Cluster-Wide Protection

    • "List all ClusterUsages tracking resource dependencies"
    • "Create a ClusterUsage to protect the shared VPC from deletion"
    • "Get the dependency details for the production database ClusterUsage"
    • "Remove the ClusterUsage for the decommissioned storage resource"

  • Namespace-Scoped Protection

    • "List all Usages in the team-alpha namespace"
    • "Create a Usage to track the dependency between the app and its database"
    • "Get the protection status for resources in the production namespace"

Runtime Configuration​

  • Deployment Settings

    • "List all DeploymentRuntimeConfigs"
    • "Create a DeploymentRuntimeConfig with custom resource limits for the AWS provider"
    • "Update the runtime config to add node affinity for the GCP provider"
    • "Get the current runtime settings for the Azure provider deployment"

  • Image & Lock Management

    • "List all ImageConfigs for custom registry settings"
    • "Create an ImageConfig to use a private registry mirror"
    • "Show the current package Locks and their resolved versions"

Prerequisites​

  • Access to Cequence AI Gateway
  • Kubernetes cluster with Crossplane installed (v1.14+)
  • Kubernetes service account with appropriate RBAC permissions
  • Bearer token or kubeconfig access to the Kubernetes API server

Step 1: Create Kubernetes Service Account Token​

Before setting up the MCP server, you need a service account with permissions to manage Crossplane resources.

1.1 Create a Service Account​

  1. Access your Kubernetes cluster where Crossplane is installed
  2. Create a dedicated service account for the AI Gateway integration
  3. Configure RBAC permissions for the Crossplane API groups:
    • apiextensions.crossplane.io for XRDs, Compositions, and EnvironmentConfigs
    • pkg.crossplane.io for Providers, Configurations, Functions, and their revisions
    • ops.crossplane.io for Operations, CronOperations, and WatchOperations
    • protection.crossplane.io for ClusterUsages and Usages

1.2 Generate a Bearer Token​

  1. Create a long-lived token for the service account
  2. Copy the generated token for use in the AI Gateway configuration
  3. Store the token securely following your organization's secret management practices

1.3 Verify Permissions​

Ensure the service account can access the required Crossplane resources:

  • CompositeResourceDefinitions and Compositions (read/write)
  • Provider, Configuration, and Function packages (read/write)
  • Operations and scheduled operations (read/write)
  • Usage and ClusterUsage resources (read/write)

Step 2: Access AI Gateway Apps​

  1. Log in to your Cequence AI Gateway dashboard
  2. Navigate to Apps in the left sidebar
  3. You'll see the list of available third-party applications

Step 3: Find and Select Crossplane API​

  1. In the Apps section, browse through the Third-party category
  2. Look for Crossplane or use the search function
  3. Click on the Crossplane API card to view details

The Crossplane API card shows:

  • Number of available endpoints
  • Integration capabilities
  • Quick description of functionality

Step 4: Create MCP Server​

  1. Click the Create MCP Server button on the Crossplane API card
  2. You'll be redirected to the MCP Server creation wizard

Step 5: Configure API Endpoints​

In the App Configuration step:

  1. Base URL: Enter your Kubernetes API server URL (e.g., https://k8s-api.your-company.com)
  2. Select API endpoints to expose to your MCP server based on your needs
  3. Click Next to proceed

Step 6: MCP Server Basic Setup​

Configure your MCP server details:

  1. MCP Server Name: Enter a descriptive name

    • Example: "Crossplane Infrastructure Control Plane"
    • This name will identify your server in the dashboard

  2. Description (Optional): Add details about the server's purpose

    • Example: "Cloud infrastructure management and composite resource operations"

  3. Production Mode: Toggle based on your needs

    • ON for production environments
    • OFF for development/testing

  4. Click Next to continue

Step 7: Configure Authentication​

  1. Authentication Type: Select Bearer Token
  2. Token: Paste the Kubernetes service account token generated in Step 1
  3. Header: Authorization: Bearer YOUR_TOKEN
  4. Test connection to verify access to the Crossplane APIs

Step 8: Configure Security​

Set up API protection features:

  1. API Protection: Toggle ON to enable

    • Protects against bot attacks, DDoS, and threats
    • Monitors for suspicious activity
    • Rate limiting and anomaly detection

  2. Protection Features (when enabled):

    • Auto-scaling protection
    • Managed infrastructure
    • Built-in monitoring
    • Zero maintenance required

  3. Click Next to continue

Step 9: Choose Deployment Method​

Select your deployment preference:

  • Fully managed deployment
  • Automatic scaling and monitoring
  • Built-in high availability
  • Features included:
    • Auto-scaling
    • Managed infrastructure
    • Built-in monitoring
    • Zero maintenance

Option B: Deploy with Helm Chart​

  • Self-managed Kubernetes deployment
  • Full control over infrastructure
  • Requires:
    • Kubernetes cluster
    • Helm 3.x installed
    • Container registry access

Click Next after selecting your deployment method.

Step 10: Review and Deploy​

Review your MCP server configuration:

  • MCP Server Name: Your chosen name
  • Base URL: Your Kubernetes API server URL
  • Selected Endpoints: Number of endpoints selected
  • Authentication: Bearer Token (Configured)
  • API Protection: Enabled/Disabled
  • Deployment: Cequence Cloud or Helm

Click Create & Deploy to finalize the setup.

Step 11: Post-Deployment Setup​

After successful deployment:

  1. Note the MCP Server URL provided

  2. Test the connection:

    • Click Test Connection
    • Verify successful authentication to the Kubernetes API
    • Confirm access to Crossplane custom resources

  3. Configure AI Agents:

    • The MCP server is now available for AI agent connections
    • Use the provided server URL in your AI agent configuration

Available Crossplane API Operations​

API Extensions (apiextensions.crossplane.io)​

  • CompositeResourceDefinitions (v1)

    • List, create, get, update, patch, and delete XRDs
    • Define custom APIs for infrastructure abstractions

  • Compositions (v1)

    • List, create, get, update, patch, and delete Compositions
    • Map custom APIs to managed infrastructure resources

  • CompositionRevisions (v1)

    • List and get CompositionRevisions
    • Track and manage Composition version history

  • EnvironmentConfigs (v1beta1)

    • List, create, get, update, patch, and delete EnvironmentConfigs
    • Manage shared configuration data for Compositions

  • Usages (v1alpha1)

    • List, create, get, update, and delete Usages
    • Track resource dependencies within API extensions

  • ManagedResourceDefinitions (v1alpha1)

    • List, create, get, update, and delete ManagedResourceDefinitions
    • Define managed resource types

  • ManagedResourceActivationPolicies (v1alpha1)

    • List, create, get, update, and delete activation policies
    • Control managed resource lifecycle policies

Package Management (pkg.crossplane.io)​

  • Providers (v1)

    • List, create, get, update, patch, and delete Providers
    • Install and manage cloud provider integrations

  • ProviderRevisions (v1)

    • List, get, and delete ProviderRevisions
    • Track Provider package version history

  • Configurations (v1)

    • List, create, get, update, patch, and delete Configurations
    • Install and manage platform Configuration packages

  • ConfigurationRevisions (v1)

    • List, get, and delete ConfigurationRevisions
    • Track Configuration package version history

  • Functions (v1)

    • List, create, get, update, patch, and delete Functions
    • Install and manage composition Function packages

  • FunctionRevisions (v1)

    • List, get, and delete FunctionRevisions
    • Track Function package version history

  • DeploymentRuntimeConfigs (v1beta1)

    • List, create, get, update, patch, and delete runtime configs
    • Customize provider deployment settings

  • ImageConfigs (v1beta1)

    • List, create, get, update, and delete ImageConfigs
    • Configure custom container image registries

  • Locks (v1beta1)

    • List and get Locks
    • View package dependency resolution state

Operations (ops.crossplane.io)​

  • Operations (v1alpha1)

    • List, create, get, and delete Operations
    • Execute one-time infrastructure operations

  • CronOperations (v1alpha1)

    • List, create, get, update, and delete CronOperations
    • Schedule recurring infrastructure operations

  • WatchOperations (v1alpha1)

    • List, create, get, update, and delete WatchOperations
    • Trigger operations based on resource changes

Protection (protection.crossplane.io)​

  • ClusterUsages (v1alpha1)

    • List, create, get, and delete ClusterUsages
    • Protect cluster-scoped resources from accidental deletion

  • Usages (v1alpha1)

    • List, create, get, and delete namespace-scoped Usages
    • Track and protect namespace-scoped resource dependencies

Using Your Crossplane MCP Server​

Setup Instructions:

Common Use Cases​

Platform Engineering​

  • Define and manage internal developer platforms with XRDs and Compositions
  • Abstract cloud complexity behind simple, self-service APIs
  • Standardize infrastructure patterns across teams
  • Distribute platform definitions as Configuration packages

Multi-Cloud Infrastructure​

  • Manage resources across AWS, Azure, and GCP from a single control plane
  • Install and configure Providers for each cloud platform
  • Create unified abstractions that work across cloud providers
  • Track Provider health and revision status

Infrastructure Automation​

  • Schedule recurring operations like backups and compliance checks
  • Set up watch-based triggers for auto-remediation
  • Manage infrastructure lifecycle with declarative operations
  • Automate routine maintenance tasks with CronOperations

Governance & Compliance​

  • Protect critical resources from accidental deletion with Usages
  • Track resource dependencies across namespaces and clusters
  • Manage package versions and enforce approved revisions
  • Audit Composition changes through revision history

Best Practices​

  1. Service Account Security:

    • Use dedicated service accounts with least-privilege RBAC
    • Rotate bearer tokens regularly following your security policy
    • Restrict access to only the Crossplane API groups needed

  2. Package Management:

    • Pin Provider and Function versions to known-good revisions
    • Test package upgrades in non-production clusters first
    • Use Configuration packages for portable platform definitions

  3. Composition Design:

    • Keep Compositions focused on a single infrastructure concern
    • Use EnvironmentConfigs for shared parameters across Compositions
    • Leverage CompositionRevisions for safe rollback of template changes

  4. Resource Protection:

    • Enable Usages for all production-critical infrastructure
    • Create ClusterUsages for shared resources like VPCs and DNS zones
    • Review dependency graphs before deleting infrastructure resources

Troubleshooting​

Common Issues​

  1. Authentication Errors

    • Verify the Kubernetes service account token is valid and not expired
    • Check that RBAC permissions include the Crossplane API groups
    • Ensure the Kubernetes API server is reachable from the network
    • Validate the bearer token format in the authorization header

  2. Resource Access Issues

    • Confirm Crossplane is installed and healthy in the target cluster
    • Check that the required Providers are installed and in a healthy state
    • Verify the service account has permissions for the specific resource types
    • Review Kubernetes RBAC audit logs for denied requests

  3. Connection Issues

    • Confirm the Kubernetes API server URL is correct and accessible
    • Verify TLS certificates if using a custom CA
    • Check firewall rules allow traffic from AI Gateway to the API server
    • Validate the base URL includes the correct port if non-standard

Getting Help​