MCP Servers

OpenChoreo provides Model Context Protocol (MCP) servers that enable AI assistants to interact with your OpenChoreo platform.

Overview

OpenChoreo provides two MCP servers:

1. Control Plane MCP Server - Provides tools for managing OpenChoreo resources (namespaces, projects, components, builds, deployments, infrastructure)
2. Observability Plane MCP Server - Provides tools for accessing observability data (logs, metrics, traces)

Each MCP server is independently accessible and requires separate configuration.

Using Both MCP Servers Together

Recommended Configuration

For the best experience, configure both the Control Plane and Observability Plane MCP servers together. Observability tools accept resource names (namespace, project, component, environment) as parameters — use the Control Plane MCP server to list and discover these names, then pass them directly to Observability tools.

Example workflow:

1. Use Control Plane MCP (list_namespaces, list_projects, list_components, list_environments) to discover resource names
2. Use those names with Observability Plane MCP tools (query_component_logs, query_traces, query_http_metrics) to fetch observability data

Available Tools

Control Plane MCP Server

The Control Plane MCP server provides 45 tools organized into the following toolsets:

Namespace Tools (3)

• list_namespaces — List all namespaces (top-level containers for organizing projects, components, and resources)
• create_namespace — Create a new namespace
• list_secret_references — List all secret references (credentials and sensitive configuration) for a namespace

Project Tools (2)

• list_projects — List all projects in a namespace (logical groupings of related components sharing deployment pipelines)
• create_project — Create a new project in a namespace

Component Tools (35)

Component Management

• list_components — List all components in a project (deployable units with independent build and deployment lifecycles)
• get_component — Get detailed component info including configuration, deployment status, and builds
• create_component — Create a new component in a project
• patch_component — Partially update a component's configuration (autoDeploy, parameters, workflow, etc.)
• get_component_workloads — Get real-time workload info (running pods, status, resource usage) across all environments
• get_component_workload — Get detailed info for a specific component workload including container configuration, endpoints, and connections
• create_workload — Create or update a workload for a component (runtime spec: containers, resources, env vars)

Component Types & Traits

• list_component_types — List all available namespace-scoped component types (WebApplication, Service, ScheduledTask, etc.)
• get_component_type_schema — Get the JSON schema for a namespace-scoped component type
• list_cluster_component_types — List all cluster-scoped component types shared across namespaces
• get_cluster_component_type — Get detailed info for a cluster-scoped component type
• get_cluster_component_type_schema — Get the JSON schema for a cluster-scoped component type
• list_traits — List all available namespace-scoped traits (autoscaling, ingress, service mesh, etc.)
• get_trait_schema — Get the JSON schema for a namespace-scoped trait
• list_cluster_traits — List all cluster-scoped traits shared across namespaces
• get_cluster_trait — Get detailed info for a cluster-scoped trait
• get_cluster_trait_schema — Get the JSON schema for a cluster-scoped trait

Releases

• list_component_releases — List all releases (immutable snapshots at a specific build) for a component
• create_component_release — Create a new release from the latest build of a component
• get_component_release — Get detailed release info including build information, image tags, and deployment status
• get_component_release_schema — Get the JSON schema for a component release's configuration options
• get_component_schema — Get the JSON schema for a component's configuration options
• get_environment_release — Get the Release spec and status for a component deployed in a specific environment

Release Bindings & Deployment

• list_release_bindings — List release bindings associating releases with environments; optionally filter by environment
• get_release_binding — Get detailed info for a specific release binding including state, overrides, and endpoints
• patch_release_binding — Update a release binding's configuration (release, overrides, traits, workload settings)
• update_release_binding_state — Update a release binding's state (Active, Suspend, or Undeploy) for a component in an environment
• deploy_release — Deploy a component release to the lowest environment in the deployment pipeline
• promote_component — Promote a release from one environment to another following the deployment pipeline

Workflows

• list_workflows — List all available workflow templates in a namespace (CI/CD pipelines executed on the build plane)
• get_workflow_schema — Get the parameter schema for a workflow template
• create_workflow_run — Create and trigger a new workflow run by specifying a workflow name and parameters
• trigger_workflow_run — Trigger a workflow run for a component using the component's configured workflow
• list_workflow_runs — List workflow run executions in a namespace; optionally filter by project and component
• get_workflow_run — Get detailed info for a workflow run including status, tasks, and timestamps

Infrastructure Tools (5)

• list_environments — List all environments (deployment targets like dev, staging, production) in a namespace
• get_environment — Get detailed environment info including data plane, deployed components, and resource quotas
• list_deployment_pipelines — List all deployment pipelines defining environment promotion order in a namespace
• get_deployment_pipeline — Get the deployment pipeline configuration showing environment progression and promotion policies
• get_observer_url — Get the observability dashboard URL for a specific environment

Platform Engineering (PE) Tools (11)

note

The PE toolset is not enabled by default. It must be explicitly enabled in the Control Plane MCP server configuration. These tools are intended for platform administrators who manage the underlying infrastructure.

• create_environment — Create a new environment in a namespace
• list_dataplanes — List all data planes (clusters where workloads execute) in a namespace
• get_dataplane — Get detailed data plane info including cluster details, capacity, and health
• create_dataplane — Create a new data plane in a namespace
• list_observability_planes — List all ObservabilityPlanes providing monitoring, logging, and tracing capabilities in a namespace
• list_buildplanes — List all build planes (dedicated build infrastructure) in a namespace
• list_cluster_dataplanes — List all cluster-scoped data planes
• get_cluster_dataplane — Get detailed info for a cluster-scoped data plane
• create_cluster_dataplane — Create a new cluster-scoped data plane
• list_cluster_buildplanes — List all cluster-scoped build planes
• list_cluster_observability_planes — List all cluster-scoped observability planes

Observability Plane MCP Server

The Observability Plane MCP server provides 7 tools covering logs, traces, and metrics:

• query_component_logs — Query runtime application logs for components (services, APIs, workers, scheduled tasks); filter by project, component, environment, time range, log levels, and search phrases
• query_workflow_logs — Query CI/CD workflow run logs capturing build, test, and deployment pipeline execution details; filter by workflow run name and task name
• query_http_metrics — Query HTTP request and latency metrics; returns time-series data for request counts (total, successful, unsuccessful) and latency percentiles (p50, p90, p99)
• query_resource_metrics — Query CPU and memory resource usage metrics; returns time-series data for usage, requests, and limits — useful for capacity planning and detecting memory leaks
• query_traces — Query distributed traces; returns a list of traces with summary information including trace ID, span count, root span details, and duration
• query_trace_spans — Query all spans within a specific distributed trace by trace ID; returns span details with timing, parent span, and service information
• get_span_details — Get full details for a specific span including attributes, resource attributes, parent span ID, and timing details

Finding MCP Server URLs

MCP server URLs follow a simple pattern based on the respective service's hostname:

• Control Plane MCP Server: <control-plane-api-hostname>/mcp
• Observability Plane MCP Server: <observer-service-hostname>/mcp

Example: Local k3d Setup

If you followed the local setup guide, your MCP server URLs will be:

Single Cluster Installation:

• Control Plane MCP Server: http://api.openchoreo.localhost:8080/mcp
• Observability Plane MCP Server: http://observer.openchoreo.localhost:11080/mcp

Multi-Cluster Installation:

• Control Plane MCP Server: http://api.openchoreo.localhost:8080/mcp
• Observability Plane MCP Server: http://observer.observability.openchoreo.localhost:11087/mcp

note

The k3d local setup examples show different ports and hostnames:

• Control plane services use port 8080
• Observability plane uses port 11080 (single cluster) or 11087 (multi-cluster)
• Multi-cluster deployments use distinct subdomain patterns for namespace isolation

Default OAuth Applications

OpenChoreo ships with pre-created OAuth applications in the default Thunder identity provider for quick-start configuration:

Application	Client ID	Grant Type	Use Case
Browser-Based (Public)	user_mcp_client	Authorization Code + PKCE	Interactive use with AI agents that support browser-based OAuth (Claude Code, Cursor)
Service (Confidential)	service_mcp_client	Client Credentials	Programmatic access, any AI agent via bearer token

These default applications eliminate the need to manually create OAuth apps for common setups.

Next Steps

To configure your AI assistant to connect to OpenChoreo MCP servers, follow the AI Configuration Guide to set up authentication and connect your AI agent.