Platform Eng Copilot

A Platform Engineering MCP Server offering reusable platform engineering workflows based on Azure and GitHub that can be run by your Agent.

1. Getting Started
2. Usage
   • Create a GitHub Repository based on a Repo template
   • Provision an Azure Deployment Environment and deploy your app
3. Architecture Overview
4. Detailed Workflow Sequence
5. MCP Components and Their Value
   • MCP Prompts: Guided Workflows
   • MCP Tools: Executable Capabilities
6. Configuration Repository

1. Getting Started

1.1 Setup GitHub Authentication

This MCP Server supports two authentication methods with GitHub:

1. GitHub Personal Access Token (PAT) - Simpler setup, suitable for testing and personal use
2. GitHub App - More secure, recommended for production use and organization-wide deployment

Option 1: GitHub Personal Access Token (PAT)

[!WARNING] Use a PAT for testing and development purposes only. For production use, authenticate with a GitHub App.

The simplest way to get started is using a GitHub Personal Access Token:

1. Create a new PAT in GitHub:

   • Go to your GitHub Settings
   • Navigate to "Developer settings" > "Personal access tokens" > "Tokens (classic)"
   • Click "Generate new token (classic)"
   • Grant the following permissions:
     • repo (Full control of private repositories)
     • workflow (Update GitHub Action workflows)
   • Copy the generated token

2. Set the token in your environment:

   • Save the token as GITHUB_PAT environment variable
   • This is the only authentication variable you need when using PAT

Option 2: GitHub App (Recommended for Organizations)

For production use and better security, create and configure a GitHub App:

1. Create a new GitHub App in your Organization:

   • Go to your Organization's Settings
   • Navigate to "GitHub Apps" under "Developer settings", Click "New GitHub App"
   • Fill in the following details:
     • GitHub App name: e.g., "Platform Engineering MCP"
     • Homepage URL: Your organization's URL
     • Webhook: Disable (not required)
     • Repository permissions:
       • Contents: Read & write
       • Metadata: Read-only
       • Actions: Read & write
       • Administration: Read & write
   • Click "Create GitHub App"

2. Generate a private key for your GitHub App:

   • After creation, scroll down to the "Private keys" section and click "Generate a private key"
   • Save the downloaded .pem file securely

3. Install the GitHub App in your Organization:

   • On the GitHub App settings page, click "Install App"
   • Select the Organization where you want to install the app
   • Choose repositories:
     • Either select "All repositories"
     • Or select specific repositories including your PE configuration repository
   • Click "Install"

4. Write down the following environment variables:

   • GITHUB_APP_ID: Found in the GitHub App's settings page (displayed as "App ID")
   • GITHUB_PRIVATE_KEY: The contents of the .pem file you downloaded
     • Open the .pem file
     • Copy all contents including "-----BEGIN RSA PRIVATE KEY-----" and "-----END RSA PRIVATE KEY-----"
     • Replace newlines with "\n" in the .env file, ask Copilot to do this for you!
   • GITHUB_INSTALLATION_ID: Found in the URL when you installed the app
     • Go to Organization Settings > GitHub Apps > Your App > Configure
     • The number in the URL after "installations/" is your installation ID
   • PE_CONFIG_REPO: Your organization's platform engineering configuration repository
     • Format: "organization-name/repository-name"

1.2 Setup your Engineering Platform on GitHub

You must either create or choose an existing repository as the one which will hold your engineering platform's configuration file. If you are authenticating with a GitHub App, this repo should be created in the organization where you have installed it.

In your chosen repository:

1. Create a file called pe.yaml.
2. Copy and paste the contents of the config/pe.yaml example file in this repo. This is just a starter example that you must edit.
3. Edit your pe.yaml file to point to your repository templates. GitHub's documentation on creating repository templates.
4. Edit your pe.yaml file to point to GitHub Organizations from where you want to source GitHub Actions workflow templates. These must be located under the .github repo's workflow-templates folder in each of the Organizations you add. GitHub's documentation on creating workflow templates for your organization.

Read more about this configuration repository at 6. Configuration Repository, which explains the structure and purpose of the pe.yaml file.

1.3 Setup the MCP Server in VSCode Insiders

In VSCode Insiders, add a new MCP Server to your User Settings JSON file. You can use either authentication method. We recommend using Docker (preferred) for easier setup and consistency.

Option 1: Using Docker (Recommended)

Docker provides an isolated environment with all dependencies pre-installed, including the Azure CLI.

With GitHub Personal Access Token

"mcp": {
    "servers": {
        "platform-eng-copilot": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e", "GITHUB_PAT",
                "-e", "AZURE_SUBSCRIPTION_ID",
                "-e", "AZURE_TENANT_ID",
                "-e", "AZURE_CLIENT_ID",
                "-e", "AZURE_CLIENT_SECRET",
                "-e", "PE_CONFIG_REPO",
                "-e", "DEVCENTER_NAME",
                "-e", "DEVCENTER_PROJECT",
                "-e", "DEVCENTER_CATALOG",
                "platform-eng-copilot"
            ],
            "env": {
                "GITHUB_PAT": "<YOUR_GITHUB_PERSONAL_ACCESS_TOKEN>",

                "AZURE_SUBSCRIPTION_ID":"<YOUR_AZURE_SUBSCRIPTION_ID>",
                "AZURE_TENANT_ID":"<YOUR_AZURE_TENANT_ID>",
                "AZURE_CLIENT_ID":"<YOUR_AZURE_CLIENT_ID>",
                "AZURE_CLIENT_SECRET":"<YOUR_AZURE_CLIENT_SECRET>",
                
                "PE_CONFIG_REPO":"<YOUR_GITHUB_ORG>/<YOUR_REPO_WITH_PE_YAML_FILE>",
                "DEVCENTER_NAME":"<YOUR_DEVCENTER_NAME>",
                "DEVCENTER_PROJECT":"<YOUR_DEVCENTER_PROJECT>",
                "DEVCENTER_CATALOG":"<YOUR_DEVCENTER_CATALOG>"
            }
        }
    }
}

With GitHub App Authentication

"mcp": {
    "servers": {
        "platform-eng-copilot": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e", "GITHUB_APP_ID",
                "-e", "GITHUB_PRIVATE_KEY",
                "-e", "GITHUB_INSTALLATION_ID",
                "-e", "AZURE_SUBSCRIPTION_ID",
                "-e", "AZURE_TENANT_ID",
                "-e", "AZURE_CLIENT_ID",
                "-e", "AZURE_CLIENT_SECRET",
                "-e", "PE_CONFIG_REPO",
                "-e", "DEVCENTER_NAME",
                "-e", "DEVCENTER_PROJECT",
                "-e", "DEVCENTER_CATALOG",
                "platform-eng-copilot"
            ],
            "env": {
                "GITHUB_APP_ID": "<YOUR_GITHUB_APP_ID>",
                "GITHUB_PRIVATE_KEY":"<YOUR_GITHUB_APP_PRIVATE_KEY_WITH_NO_BREAKLINES>",
                "GITHUB_INSTALLATION_ID":"<YOUR_GITHUB_APP_INSTALLATION_ID>",
                
                ...
            }
        }
    }
}

Option 2: Using Node.js (Alternative)

For development purposes, you can also run the MCP server directly with Node.js:

"mcp": {
    "servers": {
      "platform-eng-copilot": {
        "command": "node",
        "args": [
            "<ABSOLUTE_PATH>/platform-eng-copilot/dist/server.js"
        ],
        "env": {
          "GITHUB_PAT": "<YOUR_GITHUB_PERSONAL_ACCESS_TOKEN>",
          ...
        }
      }
   }
}

Make sure to replace all values between "<>" brackets with your actual configuration values. Only configure one authentication method - either PAT or GitHub App credentials.

2. Usage

[!NOTE] Using this MCP Server with VSCode won't allow you to use the implemented MCP Prompts, as MCP Prompts are not yet supported on VSCode.

Use VSCode Reusable prompts with the prompt files made available in this repo under .github/prompts. Think about these as reusable workflows set up by your PE Admins which will guide the Agent through a complex task across several tools in your SDLC stack.

For example, attach the create-repo.prompt.md prompt file in .github/prompts to the context and send it to GitHub Copilot.

2.1 Create a GitHub Repository based on a template

Value Proposition: Automate the creation of standardized, compliant repositories based on GitHub Repository templates.

Reusable Prompt: .github/prompts/create-repo.prompt.md

Workflow:

1. Developer expresses intent to create a new project
2. LLM gathers requirements through natural conversation
3. PE MCP Server provides appropriate GitHub repo templates based on requirements
4. LLM recommends best template and explains reasoning
5. Upon confirmation, GitHub MCP creates repository from template
6. LLM recommends appropriate CI/CD workflows from PE MCP Server
7. GitHub MCP configures workflows
8. LLM offers to provision test environment
9. Azure MCP provisions resources if requested

2.2 Provision an Azure Deployment Environment and deploy your app

Value Proposition: Let the agent pick up the right ADE template for your app, provision the environment in Azure, generate the GitHub Actions CD workflow and deploy your app.

Reusable Prompt: .github/prompts/ade-deploy.prompt.md

Workflow:

1. Developer requests environment for existing project
2. LLM determines project type and requirements
3. PE MCP Server provides appropriate environment templates
4. LLM recommends best template and explains reasoning
5. Upon confirmation, Azure MCP provisions resources
6. LLM summarizes provisioned resources and provides access information

3. Architecture Overview

This guide outlines an architecture for leveraging the Model Context Protocol (MCP) to create a powerful Platform Engineering experience through AI agents. By combining MCP's tools, prompts, and client-server architecture, we can create seamless, standardized workflows that automate complex platform engineering tasks while maintaining the human-in-the-loop element essential for critical decisions.

The architecture consists of three primary components:

1. Client LLM Interface: The entry point for users (GitHub Copilot in VS Code or GitHub.com)
2. PE MCP Server: The orchestration layer that defines workflows and exposes platform engineering capabilities
3. Product-specific MCP Servers: Specialized servers for GitHub, Azure, and other tools

    flowchart TD
    User([Developer])
    
    subgraph "Development Interfaces"
        VSCode[VS Code]
        GitHub[GitHub.com]
    end
    
    User -->|Uses| VSCode
    User -->|Uses| GitHub
    User -.->|Selects Prompt| PE_MCP
    VSCode -->|Natural Language| ClientLLM[GitHub Copilot Agent]
    GitHub -->|Natural Language| ClientLLM
    
    subgraph "MCP Ecosystem"
        ClientLLM <-->|MCP Prompts/Tools| PE_MCP[Platform Engineering MCP Server]
        ClientLLM <-->|MCP Tools| GitHub_MCP[GitHub MCP Server]
        ClientLLM <-->|MCP Tools| Azure_MCP[Azure MCP Server]
    end
    
    PE_MCP -->|Reads| ConfigRepo[(Configuration Repository)]
    
    subgraph "Orchestrated Resources"
        GitHub_MCP --> GitHubResources[GitHub Repositories
        GitHub Actions Workflows]
        Azure_MCP --> AzureResources[
        DevBox
        AKS
        App Services
        Functions
        CosmosDB
        Azure SQL
        Virtual Networks
        Load Balancers
        Azure Monitor]
    end
    
    style ClientLLM fill:#FF69B4,stroke:#fff,color:#fff
    style PE_MCP fill:#4169E1,stroke:#fff,color:#fff
    style GitHub_MCP fill:#2E8B57,stroke:#fff,color:#fff
    style Azure_MCP fill:#4682B4,stroke:#fff,color:#fff
    style ConfigRepo fill:#CD853F,stroke:#fff,color:#fff
    style AzureResources fill:#4682B4,stroke:#fff,color:#fff
    style GitHubResources fill:#2E8B57,stroke:#fff,color:#fff
    style User fill:#DEB887,stroke:#fff,color:#333
    style VSCode fill:#007ACC,stroke:#fff,color:#fff
    style GitHub fill:#24292E,stroke:#fff,color:#fff
    
    classDef default fill:#2F4F4F,stroke:#fff,color:#fff

4. Detailed Workflow Sequence

This sequence diagram demonstrates how the Platform Engineering system leverages the Model Context Protocol (MCP) to create a structured interaction between LLMs and platform tooling. The workflow follows MCP's key architectural principles:

sequenceDiagram
    User->>Client LLM: "Create a new Java project"
    Client LLM->>PE MCP Server: Invokes "create-project" prompt
    PE MCP Server->>Client LLM: Returns parameterized workflow guide
    Client LLM->>User: Requests detailed project requirements
    User->>Client LLM: Provides details (Java, Spring Boot, microservice, OAuth)
    
    Client LLM->>PE MCP Server: list-templates tool call with filters
    PE MCP Server->>Client LLM: Returns matching templates with detailed metadata
    
    Client LLM->>Client LLM: Analyzes templates against requirements
    Client LLM->>User: Recommends best template with explanation
    User->>Client LLM: Confirms template choice
    
    Client LLM->>GitHub MCP: create-repository tool call with chosen template
    GitHub MCP->>Client LLM: Repository created response
    
    Client LLM->>PE MCP Server: list-workflow-templates tool call
    PE MCP Server->>Client LLM: Returns available CI/CD workflow templates
    
    Client LLM->>Client LLM: Analyzes workflow templates against project needs
    Client LLM->>User: Recommends workflow templates with explanation
    User->>Client LLM: Confirms workflow choice
    
    Client LLM->>GitHub MCP: setup-workflows tool call with chosen workflows
    GitHub MCP->>Client LLM: Workflows configured
    
    Client LLM->>User: Ask about test environment
    User->>Client LLM: "Yes, provision test env"
    
    Client LLM->>PE MCP Server: list-environment-templates tool call
    PE MCP Server->>Client LLM: Returns matching environment templates
    Client LLM->>User: Recommends environment template with explanation
    User->>Client LLM: Confirms environment choice
    
    Client LLM->>Azure MCP: provision-resources call with chosen template
    Azure MCP->>Client LLM: Resources provisioned
    
    Client LLM->>User: Comprehensive summary of actions taken

1. Prompts as Workflow Templates: The PE MCP Server defines standardized prompt templates that guide both the LLM and user through complex platform engineering tasks. These prompts surface as discoverable, interactive elements.

   When a prompt is returned to the LLM, it includes structured guidance that helps the LLM:

   • Break down complex tasks into discrete steps
   • Select appropriate MCP tools from different servers (GitHub MCP, Azure MCP, etc.)
   • Maintain context across multiple tool invocations
   • Follow standardized workflows while adapting to specific requirements
   • Know when to seek user confirmation for critical decisions

2. Tools for Concrete Actions: Each action (creating repositories, configuring workflows, provisioning resources) is implemented as an MCP tool with well-defined parameters and validation, allowing the LLM to execute operations securely.

3. Client-Server Architecture: Following MCP's design, each service (PE, GitHub, Azure) runs as a separate server that exposes its capabilities through prompts and tools. The Client LLM acts as the coordinator, maintaining individual connections with each server.

4. Human-in-the-Loop Control: The workflow preserves MCP's human oversight model - all key decisions (template selection, workflow choices, environment provisioning) require explicit user confirmation before tools are invoked.

This approach ensures standardization while maintaining MCP's security principles and keeping humans in control of critical platform engineering decisions.

5. MCP Components and Their Value

5.1 MCP Prompts: Guided Workflows

MCP Prompts are essential for providing structured guidance to both the user and the LLM:

1. Value in Platform Engineering:

   • Workflow Standardization: Prompts define consistent workflows across the organization
   • Guided Experience: Step-by-step templates guide users through complex processes
   • Context Preservation: Maintain context throughout multi-step processes
   • Discoverability: Prompts appear as slash commands in supporting clients

2. Implementation Approach:

   • Define high-level workflow prompts that outline the entire process
   • Include dynamic parameters based on user requirements
   • Structure prompts as conversations that guide both user and LLM
   • Design prompts to anticipate common decision points

5.2 MCP Tools: Executable Capabilities

MCP Tools enable concrete actions and information retrieval:

1. Value in Platform Engineering:
   • Action Execution: Perform operations on GitHub, Azure, and other systems
   • Information Retrieval: Fetch available templates and configuration options
   • Standardization: Ensure operations follow organization standards
   • Security: Properly scoped tools with parameter validation

6. Configuration Repository

The PE MCP Server reads from a configuration file named pe.yaml that defines your platform engineering sources and templates. This file is structured into two main sections:

6.1 GitHub Workflow Organizations (github_workflow_orgs)

This section defines the GitHub organizations from which to source workflow templates. Each organization entry includes:

github_workflow_orgs:
  - name: "my-company"          # Name of the organization
    url: "https://github.com/my-company"  # Organization's GitHub URL
    description: "Main company organization containing standard CI/CD workflows"

The workflow templates must be stored in the .github/workflow-templates directory of each listed organization. This follows GitHub's standard for organization workflow templates.

6.2 GitHub Repository Templates (github_repository_templates)

This section defines repository templates that can be used as starting points for new projects. Each template includes comprehensive metadata to help the LLM make informed recommendations:

github_repository_templates:
  - name: "java-springboot-microservice"  # Template name
    url: "https://github.com/my-company/java-springboot-template"  # Template repository URL
    description: "Spring Boot microservice with OAuth2 security and API documentation"
    metadata:
      language: java              # Primary programming language
      framework: springboot       # Main framework used
      architectureType: microservice  # Type of application architecture
      features:                   # Key features and capabilities
        - oauth2
        - swagger
        - actuator
      compliance:                 # Compliance standards met
        - soc2
      use-cases:                 # Recommended use cases
        - "Backend services requiring authentication"
      complexity: medium         # Project complexity level

The metadata helps the AI agent understand:

• Technical stack (language, framework)
• Architecture patterns
• Built-in features and capabilities
• Compliance requirements met
• Intended use cases
• Project complexity

This rich metadata enables the LLM to:

1. Match templates to user requirements
2. Explain template recommendations
3. Guide users through template customization
4. Suggest appropriate workflows and environments