Control Plane OpenAPI MCP Server

This MCP (Model Context Protocol) Server provides seamless integration with the Facets Control Plane API through its OpenAPI specification. It enables AI assistants to understand, explore, and interact with the complete Facets Control Plane API, making infrastructure management and API integration more accessible through natural language interactions.

Key Features

• Real-time OpenAPI Integration
  Automatically fetches and processes the latest OpenAPI specification from Facets Control Plane, ensuring you always have access to current API documentation.

• Built-in Script Generation Guidance
  Includes an MCP prompt that provides step-by-step guidance for creating production-ready scripts that interact with Control Plane APIs, with best practices for authentication, testing, and error handling.

• Intelligent Operation Filtering
  Automatically excludes deprecated operations (17 filtered out of 566 total) to provide clean, relevant results and improved search performance.

• Advanced Fuzzy Search
  Search through 549 active operations and 500+ schemas using natural language queries with intelligent matching across summaries, descriptions, tags, and operation IDs.

• Comprehensive API Coverage
  Access complete operation details including parameters, request bodies, response schemas, and authentication requirements for all Facets Control Plane endpoints.

• Smart Caching System
  Intelligent TTL-based caching minimizes API calls while ensuring fresh data, with configurable cache duration for optimal performance.

• Detailed Schema Exploration
  Explore complex data structures with property listings, type information, and relationship mappings for all API schemas.

Available MCP Tools

Tool Name	Description
FIRST_STEP_get_api_script_guide	🚀 Start here! Loads comprehensive API script generation guide - call this tool first before using others.
refresh_api_catalog	Refreshes the API catalog by fetching the latest OpenAPI specification from the control plane.
search_api_operations	Search for operations using fuzzy matching across operation IDs, summaries, descriptions, and tags.
search_api_schemas	Search for schemas by name and description to find relevant data structures.
load_api_operation_by_operationId	Load detailed operation information by its unique operation ID including parameters and responses.
load_api_operation_by_path_and_method	Load operation details by specifying the exact API path and HTTP method.
load_api_schema_by_schemaName	Load comprehensive schema details including properties, types, and validation requirements.
call_control_plane_api	Make authenticated GET requests to the Control Plane API using the provided path.

Available MCP Prompts

Prompt Name	Description
Control Plane API Script Generation	Provides step-by-step guidance for creating production-ready scripts that interact with Control Plane APIs.

Prerequisites

The MCP Server requires uv for dependency management and execution.

Install uv with Homebrew:

brew install uv

For other installation methods, see the official uv installation guide.

Installation

Option 1: Install from PyPI (Recommended)

The easiest way to install and use the MCP server is directly from PyPI. This method always uses the latest published version.

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "control-plane-openapi": {
      "command": "uvx",
      "args": ["control-plane-openapi-mcp"],
      "env": {
        "CONTROL_PLANE_URL": "https://<customername>.console.facets.cloud",
        "FACETS_USERNAME": "<YOUR_USERNAME>",
        "FACETS_TOKEN": "<YOUR_TOKEN>",
        "FACETS_PROFILE": "default",
        "CACHE_TTL": "3600"
      }
    }
  }
}

Option 2: Install from Source

If you want to modify the code or contribute to development, clone the repository and run from source.

1. Clone the repository:

   git clone https://github.com/Facets-cloud/control-plane-openapi-mcp.git
   cd control-plane-openapi-mcp

2. Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "control-plane-openapi": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/your/cloned/control-plane-openapi-mcp", "control-plane-openapi-mcp"],
      "env": {
        "CONTROL_PLANE_URL": "https://<customername>.console.facets.cloud",
        "FACETS_USERNAME": "<YOUR_USERNAME>",
        "FACETS_TOKEN": "<YOUR_TOKEN>",
        "FACETS_PROFILE": "default",
        "CACHE_TTL": "3600"
      }
    }
  }
}

⚠️ Replace <YOUR_USERNAME> and <YOUR_TOKEN> with your actual Facets credentials.

Environment Variables

• CONTROL_PLANE_URL: Base URL of the Facets Control Plane (default: demo instance)
• FACETS_USERNAME: Your Facets username for API authentication
• FACETS_TOKEN: Your Facets access token for API authentication
• FACETS_PROFILE: Facets profile to use from credentials file (default: "default")
• CACHE_TTL: Cache time-to-live in seconds (default: 3600)

Authentication

The server supports two authentication methods:

1. Environment Variables: Set FACETS_USERNAME and FACETS_TOKEN
2. Credentials File: Configure ~/.facets/credentials with profile-based credentials

For credential setup, refer to the Facets Authentication Guide.

Usage Highlights

• Uses search_api_operations and search_api_schemas to find relevant endpoints using natural language
• Uses specific load operations to get detailed parameter and response information
• Uses call_control_plane_api to make actual API calls and get real data from your Facets environment
• Leverages the fuzzy search to find operations even with partial or approximate terms

API Coverage

The server provides access to the complete Facets Control Plane API including:

• Stack Management: Create, update, delete, and manage infrastructure stacks
• Cluster Operations: Deploy, monitor, and manage Kubernetes clusters
• Artifact Management: Handle CI/CD artifacts and routing rules
• User & Access Control: Manage users, groups, roles, and permissions
• Resource Management: Handle cloud resources and configurations
• Monitoring & Alerts: Access deployment logs, metrics, and monitoring data
• Authentication: OAuth integrations, tokens, and account management

Example Prompts

When using with Claude, try these example prompts:

"Show me all project-related operations in the Facets API"
"What are the required parameters for creating a new project?"
"Find operations related to environment deployments"
"Show me the project schema structure with all its properties"
"Generate a TypeScript interface for the project model"
"Get the current list of projects from my environment"
"Show me details of a specific project named 'my-production-project'"
"What environments are running in my Facets environment?"
"Create an example API call to get project information"
"Find all endpoints that handle artifact routing"
"What authentication methods are available in the API?"

Local Development

Setting Up Development Environment

1. Clone the repository (if not already done):

   git clone https://github.com/Facets-cloud/control-plane-openapi-mcp.git
   cd control-plane-openapi-mcp

2. Create virtual environment and install dependencies:

   uv sync

3. Activate the virtual environment:

   source .venv/bin/activate  # On macOS/Linux
   # or
   .venv\Scripts\activate     # On Windows

Testing the MCP Server

# Start the MCP server (will wait for stdin input)
uv run control-plane-openapi-mcp

# Test with custom OpenAPI URL
FACETS_OPENAPI_URL="https://your-instance.com/v3/api-docs" uv run control-plane-openapi-mcp

Development Workflow

1. Make changes to the source code
2. Test locally using the example scripts
3. Verify MCP integration with Claude Desktop
4. Run validation to ensure no regressions
5. Commit changes with descriptive messages

Project Structure

control_plane_openapi_mcp/
├── __init__.py              # Package initialization
├── config.py                # Configuration and MCP setup
├── server.py                # Main MCP server entry point
├── tools.py                 # MCP tool implementations
└── core/                    # Core functionality
    ├── models.py            # Pydantic data models
    ├── spec_loader.py       # OpenAPI spec fetching and processing
    ├── spec_processor.py    # Operation and schema extraction
    ├── search.py            # Fuzzy search engine
    ├── cache.py             # TTL-based caching
    └── service.py           # Main orchestrating service

---

Architecture

• SpecLoader: Fetches and processes OpenAPI specifications with JSON reference resolution
• SpecProcessor: Extracts operations and schemas while filtering deprecated endpoints
• SearchEngine: Provides fuzzy search capabilities with configurable matching thresholds
• OpenAPIService: Main service coordinating all components with intelligent caching
• SimpleCache: TTL-based caching for performance optimization
• MCP Tools: Specialized tools exposing functionality to AI assistants

License

This project is licensed under the MIT License. You are free to use, modify, and distribute it under its terms.