EdgeConnect

• 1: EdgeConnect SDK
• 2: EdgeConnect Client
• 3: Terraform provider for Edge cloud
• 4: Forgejo Actions
• 5: Edge Connect MCP Server

1 - EdgeConnect SDK

Overview

The EdgeConnect SDK is a Go library which provides a simple method for interacting with Edge Connect within programs. It is designed to be used by other tools, such as the EdgeConnect Client or Terraform provider,

Key Features

• Allows querying endpoints without the need to manage API calls and responses directly
• Wraps the existing Edge Connect API
• Supports multiple unnumbered versions of the API

Purpose in EDP

No system can be considered useful unless it is actually, in practice, used. While the Edge Connect console and API are essential tools to allow the platform to be used by developers, there are numerous use cases for interaction that is automated but simpler to use than an API. These include a command-line tool and Terraform provider.

While each such tool could simply independently wrap existing endpoints, this is generally too low-level for sustainable development. It would involve extensive boilerplate code in each such package, plus small changes to API endpoints or error handling may require constant rework.

To avoid this, the Edge Connect SDK aims to provide a common library for interacting with EdgeConnect, allowing the abstraction of HTTP requests and authentication procedures while nonetheless allowing access directly to the endpoints available.

Repository

Code: https://edp.buildth.ing/DevFW-CICD/edge-connect-client

Documentation: https://edp.buildth.ing/DevFW-CICD/edge-connect-client/src/branch/main/sdk

Getting Started

Prerequisites

• Golang
• Edge Connect credentials

Quick Start

[Step-by-step guide to get started with this component]

1. Simply import the SDK to your project
2. Initialise and configure a client with your credentials
3. Build your code around the existing endpoints

Verification

[How to verify the component is working correctly]

Usage Examples

See README for simple code examples, or repositories for EdgeConnect Client and Terraform provider for full projects relying on it.

Troubleshooting

Varying code versions

Problem: While the Edge Connect API does not (at time of writing) have different semantic versions, it does have different iterations which function differently. The SDK provides two different libraries, labelled v1 and v2 and referring to API definitions similarly stored as v1 and v2.

Solution: If you receive errors when using the SDK, consider changing the version you import:

import v1 "edp.buildth.ing/DevFW-CICD/edge-connect-client/sdk/edgeconnect"
import v2 "edp.buildth.ing/DevFW-CICD/edge-connect-client/v2/sdk/edgeconnect/v2"

Status

Maturity: Beta

2 - EdgeConnect Client

Overview

The EdgeConnect Client is a command-line tool for managing EdgeConnect applications and instances. It is built using our Golang SDK, and supports functionality to create, destroy, describe and list various resources.

The tool provides both imperative commands (for direct resource management) and declarative workflows (using YAML configuration files) to deploy applications across multiple edge cloudlets. It supports different EdgeConnect deployment environments through an API version selector.

Key Features

• Dual workflow support: Imperative commands for direct operations, declarative YAML for infrastructure-as-code
• Multi-cloudlet deployment: Deploy applications to multiple edge locations from a single configuration
• Deployment planning: Preview and approve changes before applying them (dry-run mode)
• Environment compatibility: Works with different EdgeConnect deployment environments (configured via api-version)
• CI/CD ready: Designed for automated deployments with auto-approve and exit codes

Purpose in EDP

No system can be considered useful unless it is actually, in practice, used. While the Edge Connect console and API are essential tools to allow the platform to be used by developers, there are numerous use cases for interaction that is automated but simpler to use than an API.

The EdgeConnect Client bridges the gap between manual console operations and direct API integration, enabling automated deployments in CI/CD pipelines, infrastructure-as-code workflows, and scripted operations while maintaining simplicity and usability.

Repository

Code: https://edp.buildth.ing/DevFW-CICD/edge-connect-client

Releases: https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases

Getting Started

Prerequisites

• Access credentials for the EdgeConnect platform (username and password)
• Knowledge of your target deployment environment (determines api-version setting)
• For Kubernetes deployments: K8s manifest files
• For Docker deployments: Docker image reference

Quick Start

1. Download the Edge Connect Client binary from the Forgejo releases page for your platform (Linux, macOS, or Windows)
2. Extract and move to your PATH: tar -xzf edge-connect-client_*.tar.gz && sudo mv edge-connect /usr/local/bin/
3. Configure authentication using environment variables or a config file (see Configuration section)
4. Verify installation: edge-connect --help

Verification

Run edge-connect app list --org <your-org> --region <region> to verify you can authenticate and communicate with the EdgeConnect API.

Usage Examples

Declarative Deployment (Recommended)

Create an EdgeConnectConfig.yaml file defining your application and deployment targets, then apply it:

edge-connect apply -f EdgeConnectConfig.yaml

Use --dry-run to preview changes without applying them, and --auto-approve for automated CI/CD workflows.

Imperative Commands

Direct resource management using CLI commands:

# Create an application
edge-connect app create --org myorg --name myapp --version 1.0.0 --region EU

# Create an instance on a specific cloudlet
edge-connect instance create --org myorg --name myinstance \
  --app myapp --version 1.0.0 --region EU \
  --cloudlet Munich --cloudlet-org TelekomOp --flavor EU.small

# List resources
edge-connect app list --org myorg --region EU
edge-connect instance list --org myorg --region EU

# Delete resources
edge-connect instance delete --org myorg --name myinstance --region EU \
  --cloudlet Munich --cloudlet-org TelekomOp
edge-connect app delete --org myorg --name myapp --version 1.0.0 --region EU

Integration Points

• EdgeConnect API: Communicates with EdgeConnect platform APIs for all resource operations
• EdgeConnect SDK: Built on top of the Golang SDK, sharing authentication and client implementation
• CI/CD Pipelines: Designed for integration with GitLab CI, GitHub Actions, and other automation tools
• Infrastructure-as-Code: YAML configuration files enable GitOps workflows

Configuration

Global Settings

The client can be configured via config file, environment variables, or command-line flags (in order of precedence: flags > env vars > config file).

Config File (~/.edge-connect.yaml or use --config flag):

base_url: "https://hub.apps.edge.platform.mg3.mdb.osc.live"
username: "your-username@example.com"
password: "your-password"
api_version: "v2"  # v1 or v2 - identifies deployment environment

Environment Variables:

• EDGE_CONNECT_BASE_URL: API base URL
• EDGE_CONNECT_USERNAME: Authentication username
• EDGE_CONNECT_PASSWORD: Authentication password
• EDGE_CONNECT_API_VERSION: API version selector (v1 or v2, default: v2)

Global Flags (available on all commands):

• --base-url: API base URL
• --username: Authentication username
• --password: Authentication password
• --api-version: API version selector (v1 or v2) - specifies which deployment environment to target
• --config: Path to config file
• --debug: Enable debug logging

Note on API Versions: The api-version setting (v1 or v2) is an internal label used to distinguish between different EdgeConnect deployment environments, not an official API version designation from the platform.

Commands

App Management (edge-connect app <command>):

CLI command app corresponds to App in the platform console.

• create: Create app (flags: --org, --name, --version, --region)
• show: Show app details (flags: same as create)
• list: List apps (flags: --org, --region, optional: --name, --version)
• delete: Delete app (flags: --org, --name, --version, --region)

App Instance Management (edge-connect instance <command>):

CLI command instance corresponds to App Instance in the platform console.

• create: Create app instance (flags: --org, --name, --app, --version, --region, --cloudlet, --cloudlet-org, --flavor)
• show: Show app instance details (flags: --org, --name, --cloudlet, --cloudlet-org, --region, --app-id)
• list: List app instances (flags: same as show, all optional)
• delete: Delete app instance (flags: --org, --name, --cloudlet, --cloudlet-org, --region)

Declarative Operations:

• apply: Deploy from YAML (flags: -f <file>, --dry-run, --auto-approve)
• delete: Delete from YAML (flags: -f <file>, --dry-run, --auto-approve)

YAML Configuration Format

The EdgeConnectConfig.yaml file defines apps and their deployment targets:

kind: edgeconnect-deployment
metadata:
  name: "my-app"                    # App name (required)
  appVersion: "1.0.0"               # App version (required)
  organization: "myorg"             # Organization (required)

spec:
  # Choose ONE: k8sApp OR dockerApp
  k8sApp:
    manifestFile: "./k8s-deployment.yaml"  # Path to K8s manifest

  # OR dockerApp:
  #   image: "registry.example.com/myimage:tag"
  #   manifestFile: "./docker-compose.yaml"  # Optional

  # Deployment targets (at least one required)
  infraTemplate:
    - region: "EU"                  # Region (required)
      cloudletOrg: "TelekomOp"      # Cloudlet provider (required)
      cloudletName: "Munich"        # Cloudlet name (required)
      flavorName: "EU.small"        # Instance size (required)
    - region: "US"
      cloudletOrg: "TelekomOp"
      cloudletName: "gardener-shepherd-test"
      flavorName: "default"

  # Optional network configuration
  network:
    outboundConnections:
      - protocol: "tcp"             # tcp, udp, or icmp
        portRangeMin: 80
        portRangeMax: 80
        remoteCIDR: "0.0.0.0/0"
      - protocol: "tcp"
        portRangeMin: 443
        portRangeMax: 443
        remoteCIDR: "0.0.0.0/0"

  # Optional deployment strategy (default: recreate)
  deploymentStrategy: "recreate"    # recreate, blue-green, or rolling

Key Points:

• Manifest file paths are relative to the config file location
• Multiple infraTemplate entries deploy to multiple cloudlets simultaneously
• Network configuration is optional; outbound connections default to platform settings
• Deployment strategy currently only supports “recreate” (others planned)

Troubleshooting

Authentication Failures

Problem: Errors like “authentication failed” or “unauthorized”

Solution:

• Verify credentials are correct in config file or environment variables
• Ensure base_url includes the scheme (https://) and has no trailing path
• Check that you’re connecting to the correct cloud instance (Edge or Orca)
• Ensure the correct api-version is set for your deployment environment

“Configuration validation failed” Errors

Problem: YAML configuration file validation errors

Solution:

• Check that all required fields are present (name, appVersion, organization)
• Ensure you have exactly one of k8sApp or dockerApp (not both, not neither)
• Verify manifest file paths exist relative to the config file location
• Check for leading/trailing whitespace in string values
• Ensure at least one infraTemplate entry is defined

Wrong API Version or Cloud Instance

Problem: Commands work but resources don’t appear in the console, or vice versa

Solution: Verify both the base_url and api-version match your target environment. There are two cloud instances (Edge and Orca) with different URLs and API versions. Check with your platform administrator for the correct configuration.

Status

Maturity: Production

Additional Resources

• EdgeConnect SDK Documentation
• Edge Cloud: Console | API Docs
• Orca Cloud: Console | API Docs
• Source Code Repository

3 - Terraform provider for Edge cloud

Overview

This work-in-progress Terraform provider for Edge cloud allows orchestration of selected resources using flexible, concise HCL. This allows deployment to Edge Cloud through a familiar format, abstracting away specific endpoints and authentication elements, and allowing seamless combination of Edge resources with others: on OTC, other clouds, or local utilities.

Key Features

• Interact with Apps and AppInstances using widely-used Terraform framework
• Using Terraform’s systems, provide minimal configuration: just an endpoint and credentials, then no need to deal with headers or other API boilerplate
• Also works with community-driven OpenTofu
• Provider currently under development: more features can be added when requested.

Purpose in EDP

Interacting with infrastructure is a complex process, with many parameters and components working together. Doing so by clicking buttons in a web UI (“ClickOps”) is extremely difficult to scale, rapidly becoming highly confusing.

Instead, automations are possible through APIs and SDKs. Working directly with an API (e.g. via curl) inevitably tends to involve large amounts of boilerplate code to manage authentication, rarely-changing configuration such as region/tenant selection, and more. When one resource (say, a web server) must interact with another (say, a DNS record), the cross-references further increase this complexity.

An SDK mitigates this complexity when coding software, by providing library functions which interact with the API in abstracted ways which require a minimum of necessary information. Our SDK for Edge Connect is described in a separate section.

However, when simply wanting to deploy infrastructure in isolation - say, updating the status of a Kubernetes or App resource after a change in configuration - an SDK is still an overly complicated tool.

This is where Terraform or its community-led alternative OpenTofu, come in. They provide a simple language for defining resources, with a level of abstraction that retains the power and flexibility of the API while greatly simplifying definitions and execution.

Terraform is widely used for major infrastructure systems such as AWS, Azure or general Kubernetes. However, it is highly flexible, supporting a range of resource types which are not inherently tied to infrastructure: file manipulation; package setup through Ansible; secret generation in Vault.

As a result of this breadth of functionality and cross-compatibility, Terraform support is considered by some as necessary for a platform to be used ‘seriously’ - that is, at scale, or in major workloads. Our provider thus unlocks broad market relevance for the platform in a way few other tools or features could.

Repository

Code: https://edp.buildth.ing/DevFW-CICD/terraform-provider-edge-connect

Documentation: Provider is intended to ultimately wrap each resource-based endpoint of the Edge API, but currently supports a limited subset of resources.

Getting Started

Prerequisites

• Terraform or OpenTofu
• Edge access and credentials

Quick Start

1. Configure Terraform to use the provider by including it in provider.tf
2. In the same directory, create terraform resources in .tf files according to the spec
3. Set up credentials using environment variables or a provider block
4. Run terraform init in the directory
5. Execute terraform plan and/or terraform apply to deploy your application
6. terraform destroy can be used to remove all deployed resources

Verification

If terraform apply completes successfully (without errors), the provider is working correctly. You can also manually validate in the Edge UI that your resources have been deployed/reconfigured as Terraform indicated.

Status

Maturity: Experimental

Additional Resources

• Terralist
• Terraform
• OpenTofu
• Edge Connect API

Integration Points

• Edge Connect SDK: The provider uses the Edge Connect SDK under the hood.
• Terralist: The provider is published using a custom instance of Terralist. This can only be written to with a login via Forgejo, but can be read publicly. See the repository README for more information.

Component Architecture (C4)

4 - Forgejo Actions

Overview

The EdgeConnect Actions are custom composite actions for use in Forgejo/GitHub Actions that automate EdgeConnect application deployments in CI/CD pipelines. They wrap the EdgeConnect Client to provide a simple, declarative way to deploy and delete applications without manual CLI installation or configuration.

Two actions are available:

• edge-connect-deploy-action: Deploys applications using declarative YAML configuration
• edge-connect-delete-action: Deletes applications and their instances from EdgeConnect

Key Features

• Zero installation: Actions automatically download and use the EdgeConnect Client
• Declarative workflow: Deploy applications using YAML configuration files
• CI/CD optimized: Designed for automated pipelines with auto-approve and dry-run support
• Version pinning: Specify exact EdgeConnect Client version for reproducible builds
• Secrets management: Credentials passed securely through workflow secrets
• Compatible with GitHub and Forgejo Actions: Works in both ecosystems

Purpose in EDP

CI/CD automation is essential for modern development workflows. While the EdgeConnect Client provides powerful deployment capabilities, integrating it into CI/CD pipelines requires downloading binaries, managing credentials, and configuring authentication for each workflow run.

These actions eliminate that boilerplate by:

• Automatically fetching the correct Client version
• Handling authentication setup
• Providing a clean, reusable action interface
• Reducing pipeline configuration to a few lines

This enables teams to focus on application configuration rather than pipeline plumbing, while maintaining the full power of declarative EdgeConnect deployments.

The actions complement the Terraform provider by offering a simpler option for teams already using Forgejo/GitHub Actions who want deployment automation without adopting Terraform.

Repository

Deploy Action: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action

Delete Action: https://edp.buildth.ing/DevFW-CICD/edge-connect-delete-action

Demo Repository: https://edp.buildth.ing/DevFW-CICD/edgeconnect-action-demo

Getting Started

Prerequisites

• Forgejo or GitHub repository with Actions enabled
• EdgeConnect access credentials (username and password)
• EdgeConnectConfig.yaml file defining your application (see YAML Configuration Format)
• For Kubernetes apps: K8s manifest file referenced in the config
• Repository secrets configured with EdgeConnect credentials

Quick Start

1. Create an EdgeConnectConfig.yaml file in your repository defining your application (see Client documentation)
2. Add EdgeConnect credentials as repository secrets:
   • EDGEXR_PLATFORM_USERNAME
   • EDGEXR_PLATFORM_PASSWORD
3. Create a workflow file (e.g., .forgejo/workflows/deploy.yaml) using the action
4. Commit and push to trigger the workflow

Verification

After the workflow runs successfully:

• Check the workflow logs for deployment status
• Verify resources appear in the EdgeConnect console
• Test application endpoints are accessible

Usage Examples

Minimal Deploy Action

- name: Deploy to EdgeConnect
  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
  with:
    configFile: ./EdgeConnectConfig.yaml
    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}

Minimal Delete Action

- name: Delete from EdgeConnect
  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-delete-action@main
  with:
    configFile: ./EdgeConnectConfig.yaml
    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}

Complete Workflow Example

A typical deployment workflow that builds, tags, and deploys:

name: deploy

on:
  workflow_run:
    workflows: [build]
    types:
      - completed
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Update manifest with image tag
        run: |
          sha="${{ github.sha }}"
          shortSha="${sha:0:7}"
          echo "Setting image version to: registry.example.com/myapp:${shortSha}"
          sed -i "s@###IMAGETAG###@registry.example.com/myapp:${shortSha}@g" ./k8s-deployment.yaml

      - name: Deploy to EdgeConnect
        uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
        with:
          configFile: ./EdgeConnectConfig.yaml
          baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
          username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
          password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}

Dry-Run Mode

Preview changes without applying them:

- name: Preview deployment
  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
  with:
    configFile: ./EdgeConnectConfig.yaml
    dryRun: 'true'
    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}

Version Pinning

Use a specific EdgeConnect Client version:

- name: Deploy with specific version
  uses: https://edp.buildth.ing/DevFW-CICD/edge-connect-deploy-action@main
  with:
    configFile: ./EdgeConnectConfig.yaml
    version: 'v2.0.1'
    baseUrl: https://hub.apps.edge.platform.mg3.mdb.osc.live
    username: ${{ secrets.EDGEXR_PLATFORM_USERNAME }}
    password: ${{ secrets.EDGEXR_PLATFORM_PASSWORD }}

Integration Points

• EdgeConnect Client: Actions download and execute the Client CLI tool
• EdgeConnect SDK: Client uses the SDK for all API interactions
• Forgejo/GitHub Actions: Native integration with both action ecosystems
• EdgeConnect API: All operations communicate with EdgeConnect platform APIs
• Container Registries: Works with any registry for application images

Configuration

Action Inputs

Both deploy and delete actions accept the same inputs:

YAML Configuration File

The configFile parameter points to an EdgeConnectConfig.yaml that defines your application and deployment targets. See the EdgeConnect Client YAML Configuration Format for the complete specification.

Example structure:

kind: edgeconnect-deployment
metadata:
  name: "my-app"
  appVersion: "1.0.0"
  organization: "myorg"
spec:
  k8sApp:
    manifestFile: "./k8s-deployment.yaml"
  infraTemplate:
    - region: "EU"
      cloudletOrg: "TelekomOp"
      cloudletName: "Munich"
      flavorName: "EU.small"

Secrets Management

Configure repository secrets in Forgejo/GitHub:

1. Navigate to repository Settings → Secrets
2. Add secrets:
   • Name: EDGEXR_PLATFORM_USERNAME, Value: your EdgeConnect username
   • Name: EDGEXR_PLATFORM_PASSWORD, Value: your EdgeConnect password
3. Reference in workflows using ${{ secrets.SECRET_NAME }}

Troubleshooting

Action Fails with “Failed to download edge-connect-client”

Problem: Action cannot download the Client binary

Solution:

• Verify the version parameter matches an actual release version
  • Ensure the release exists at https://edp.buildth.ing/DevFW-CICD/edge-connect-client/releases
• Check network connectivity from the runner
• Try using default version by omitting the version parameter

Authentication Errors

Problem: “authentication failed” or “unauthorized” errors

Solution:

• Verify secrets are correctly configured in repository settings
• Check secret names match exactly (case-sensitive)
• Ensure baseUrl is correct for your target environment (Edge vs Orca)
• Confirm credentials work by testing with the client

“Configuration validation failed”

Problem: YAML configuration file validation errors

Solution:

• Verify configFile path is correct relative to repository root
• Check YAML syntax is valid (use a YAML validator)
• Ensure all required fields are present (see Client docs)
• Verify manifest file paths in the config exist and are correct

Resources Not Appearing in Console

Problem: Action succeeds but resources don’t appear in EdgeConnect console

Solution:

• Verify you’re checking the correct environment (Edge vs Orca)
• Ensure baseUrl parameter matches the console you’re viewing
• Check organization name in config matches your console access
• Review action logs for any warnings or skipped operations

Deployment Succeeds but App Doesn’t Work

Problem: Deployment completes but application is not functioning

Solution:

• Check application logs in the EdgeConnect console
• Verify image tags are correct (common issue with placeholder replacement)
• Ensure manifest files reference correct image registry and paths
• Check network configuration allows required outbound connections
• Verify cloudlet has sufficient resources for the specified flavor

Status

Maturity: Production

Additional Resources

• EdgeConnect Client Documentation
• EdgeConnect SDK Documentation
• Terraform Provider Documentation
• EdgeConnect Console
• Demo Repository
• Forgejo Actions Documentation

5 - Edge Connect MCP Server

Overview

The Edge Connect MCP Server enables AI assistants like Claude to directly interact with EdgeConnect through the Model Context Protocol (MCP). This allows natural language requests to manage applications and instances, with AI agents autonomously executing API operations on your behalf.

MCP is an open protocol that connects AI systems to data sources and tools. In agentic coding workflows, AI assistants can plan, execute, and verify infrastructure operations through conversational interfaces while maintaining full visibility and control.

Key Features

• Natural language control: Manage EdgeConnect resources through conversational AI interactions
• Full API coverage: Supports all App and AppInstance operations (create, list, show, update, delete, refresh)
• Rich visualizations: Interactive dashboards and detail views via MCP-UI. Tools return both JSON and HTML responses — clients like Goose render the HTML dashboards, while others use the JSON data.
• Multiple integration modes: Local stdio for desktop apps, remote HTTP/SSE for web clients
• Production-ready security: OAuth 2.1 authorization with JWT validation and PKCE for remote deployments
• Graceful fallbacks: Returns structured JSON when UI resources aren’t supported

Purpose in EDP

Manual infrastructure operations don’t scale, but writing automation scripts for every task is costly. The Edge Connect MCP Server bridges this gap by enabling AI assistants to act as automation agents — understanding natural language requests, planning operations, and executing them through the EdgeConnect API.

This expands EdgeConnect accessibility beyond developers comfortable with CLIs and APIs, enabling infrastructure management through conversation while maintaining the precision and repeatability of programmatic control. For teams already using AI coding assistants, it integrates EdgeConnect operations directly into their development workflow.

Repository

Code: https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp

Releases: https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp/releases

Getting Started

Prerequisites

• EdgeConnect access credentials (username/password or bearer token)
• For Claude Desktop: macOS or Windows with Claude Desktop installed
• For Claude Code: Claude CLI installed
• For remote deployment: Server infrastructure and optional OAuth provider

Quick Start

1. Download the binary from releases or build from source:

   go build -o edge-connect-mcp
   

2. Configure for Claude Desktop by editing the config file:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "edge-connect": {
         "command": "/path/to/edge-connect-mcp",
         "env": {
           "EDGE_CONNECT_BASE_URL": "https://hub.apps.edge.platform.mg3.mdb.osc.live",
           "EDGE_CONNECT_AUTH_TYPE": "credentials",
           "EDGE_CONNECT_USERNAME": "your-username",
           "EDGE_CONNECT_PASSWORD": "your-password",
           "EDGE_CONNECT_DEFAULT_REGION": "EU"
         }
       }
     }
   }
   

3. Restart Claude Desktop and verify the MCP server appears in the tools menu

Verification

Ask Claude: “List my EdgeConnect applications in the EU region.” If the MCP server is configured correctly, Claude will retrieve and display your applications.

Usage Examples

Conversational Operations

The MCP server enables natural interactions like:

• “Show me all running application instances”
• “Create a new app called nginx-test using the nginx:latest image”
• “Deploy my-app version 2.0 to the Munich cloudlet”
• “Delete all instances of old-app”

Claude interprets these requests, selects appropriate tools, and executes the operations while explaining each step.

Integration with Claude Code CLI

Configure the MCP server using the Claude CLI:

# Add MCP server
claude mcp add edge-connect

# Configure
claude mcp edit edge-connect --set command=/path/to/edge-connect-mcp
claude mcp edit edge-connect --set-env EDGE_CONNECT_BASE_URL=https://hub.apps.edge.platform.mg3.mdb.osc.live
claude mcp edit edge-connect --set-env EDGE_CONNECT_AUTH_TYPE=credentials
claude mcp edit edge-connect --set-env EDGE_CONNECT_USERNAME=your-username
claude mcp edit edge-connect --set-env EDGE_CONNECT_PASSWORD=your-password

# Test
claude mcp test edge-connect

Remote Deployment

For team access or web-based clients, run in remote mode with OAuth 2.1:

# Edge Connect configuration
export EDGE_CONNECT_BASE_URL="https://hub.apps.edge.platform.mg3.mdb.osc.live"
export EDGE_CONNECT_AUTH_TYPE="credentials"
export EDGE_CONNECT_USERNAME="your-username"
export EDGE_CONNECT_PASSWORD="your-password"

# MCP server configuration
export MCP_SERVER_MODE="remote"
export MCP_REMOTE_HOST="0.0.0.0"
export MCP_REMOTE_PORT="8080"

# OAuth 2.1 configuration
export OAUTH_ENABLED="true"
export OAUTH_RESOURCE_URI="https://mcp.example.com"
export OAUTH_AUTH_SERVERS="https://auth.example.com"
export OAUTH_ISSUER="https://auth.example.com"
export OAUTH_JWKS_URL="https://auth.example.com/.well-known/jwks.json"

./edge-connect-mcp -mode remote

Web clients connect via http://your-server:8080/mcp using OAuth bearer tokens.

Note: No shared remote server endpoint is currently deployed. Users must run their own instance locally or on their infrastructure. A shared deployment at mcp.edp.buildth.ing is being evaluated for Q2 2026 (IPCEICIS-7086).

Configuration

Environment Variables

EdgeConnect API (required):

• EDGE_CONNECT_BASE_URL: API endpoint
• EDGE_CONNECT_AUTH_TYPE: Authentication method (token, credentials, or none)
• EDGE_CONNECT_TOKEN: Bearer token (when auth_type=token)
• EDGE_CONNECT_USERNAME: Username (when auth_type=credentials)
• EDGE_CONNECT_PASSWORD: Password (when auth_type=credentials)

Note on Authentication: Username/password credentials are currently required because federated access with short-lived credentials is not yet available. The Platform Team plans to provide federated authentication in the coming months. A dedicated story for integrating the standard EdgeConnect auth flow (using cached credentials from gardenctl or a browser-based OIDC login) is tracked in IPCEICIS-7090 for Q2 2026.

Optional:

• EDGE_CONNECT_DEFAULT_REGION: Default region (default: EU)
• EDGE_CONNECT_DEBUG: Enable debug logging (true or 1)

Remote Mode:

• MCP_SERVER_MODE: Server mode (stdio or remote)
• MCP_REMOTE_HOST: Bind address (default: 0.0.0.0)
• MCP_REMOTE_PORT: Port (default: 8080)
• MCP_REMOTE_AUTH_REQUIRED: Enable simple bearer token auth (true or false)
• MCP_REMOTE_AUTH_TOKENS: Comma-separated bearer tokens

OAuth 2.1 (recommended for production remote deployments):

• OAUTH_ENABLED: Enable OAuth (true or false)
• OAUTH_RESOURCE_URI: Protected resource identifier
• OAUTH_AUTH_SERVERS: Authorization server URLs (comma-separated)
• OAUTH_ISSUER: JWT token issuer
• OAUTH_JWKS_URL: JSON Web Key Set endpoint

Command-Line Flags

Flags override environment variables:

• -mode: Server mode (stdio or remote)
• -host: Bind address for remote mode
• -port: Port for remote mode

Available Tools

App Management:

• create_app: Create new application
• show_app: Retrieve application details (with UI visualization)
• list_apps: List applications matching filters (with UI dashboard)
• update_app: Update existing application
• delete_app: Delete application (idempotent)

App Instance Management:

• create_app_instance: Create instance on cloudlet
• show_app_instance: Retrieve instance details
• list_app_instances: List instances matching filters (with UI dashboard)
• update_app_instance: Update instance configuration
• refresh_app_instance: Refresh instance state
• delete_app_instance: Delete instance (idempotent)

MCP-UI Visualization Support

This server implements MCP-UI, returning both structured JSON and rich HTML visualizations in every response. The HTML includes interactive dashboards with status indicators, filtering, and visual organization of infrastructure data.

MCP clients that support UI resources (currently Goose) will automatically render these HTML views. Clients without UI support (like Claude Desktop and Claude Code) receive the JSON data and work normally without the visual enhancements.

Operations with UI support include list_apps, show_app, list_app_instances, and show_app_instance.

Integration Points

• EdgeConnect API: Communicates with EdgeConnect platform for all operations
• EdgeConnect SDK: Built on the Go SDK for authentication and API client implementation
• MCP-UI: All tools return dual-format responses (JSON + HTML). Clients that support UI resources (like Goose) render rich HTML dashboards; others use the JSON data automatically.
• Claude Desktop/Code: Primary integration targets for AI-assisted infrastructure management
• OAuth Providers: Supports Auth0, Amazon Cognito, Keycloak, and other OAuth 2.1-compliant systems

Troubleshooting

MCP Server Not Appearing

Problem: Claude Desktop doesn’t show the edge-connect tools

Solution:

• Verify the config file path is correct for your OS
• Check the command path points to the binary
• Restart Claude Desktop after configuration changes
• Check Claude Desktop logs for MCP initialization errors

Authentication Errors

Problem: Operations fail with “authentication failed” or “unauthorized”

Solution:

• Verify credentials in environment variables are correct
• Ensure EDGE_CONNECT_BASE_URL uses HTTPS and has no trailing slash
• Check EDGE_CONNECT_AUTH_TYPE matches your credential type
• Test credentials with the EdgeConnect CLI first

Remote Server Connection Issues

Problem: Can’t connect to remote MCP server

Solution:

• Verify server is running: check /health endpoint returns {"status":"healthy"}
• If OAuth is enabled, ensure client has valid JWT bearer token
• Check firewall rules allow connections to the MCP port
• Verify CORS headers if connecting from web clients
• Review server logs for authentication or validation errors

Upcoming Features

The following capabilities are planned for Q2 2026:

Status

Maturity: Production

Additional Resources

• Model Context Protocol Specification
• MCP-UI Documentation
• EdgeConnect API Documentation
• Claude Desktop
• OAuth 2.1 RFC
• Source Code Repository