From 97e28f45ab458ce0dfd38a3904318d53c2526479 Mon Sep 17 00:00:00 2001 From: Martin McCaffery Date: Wed, 21 Jan 2026 18:00:15 +0100 Subject: [PATCH] Add documentation for EdgeConnect MCP server --- .../en/docs/edgeconnect/edge-connect-mcp.md | 257 ++++++++++++++++++ 1 file changed, 257 insertions(+) create mode 100644 content/en/docs/edgeconnect/edge-connect-mcp.md diff --git a/content/en/docs/edgeconnect/edge-connect-mcp.md b/content/en/docs/edgeconnect/edge-connect-mcp.md new file mode 100644 index 0000000..06d9407 --- /dev/null +++ b/content/en/docs/edgeconnect/edge-connect-mcp.md @@ -0,0 +1,257 @@ +--- +title: Edge Connect MCP Server +linkTitle: MCP Server +weight: 40 +description: Model Context Protocol server enabling AI-assisted EdgeConnect management +--- + +## Overview + +The Edge Connect MCP Server enables AI assistants like [Claude](https://claude.ai) to directly interact with EdgeConnect through the [Model Context Protocol](https://modelcontextprotocol.io/) (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](https://github.com/MCP-UI-Org/mcp-ui). Tools return both JSON and HTML responses — clients like [Goose](https://github.com/block/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](https://swagger.edge.platform.mg3.mdb.osc.live/). + +This expands EdgeConnect accessibility beyond developers comfortable with [CLIs](/docs/edgeconnect/edgeconnect-client/) and [APIs](https://swagger.edge.platform.mg3.mdb.osc.live/), 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](https://claude.ai/download): macOS or Windows with Claude Desktop installed +* For [Claude Code](https://github.com/anthropics/claude-code): Claude CLI installed +* For remote deployment: Server infrastructure and optional OAuth provider + +### Quick Start + +1. Download the binary from [releases](https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp/releases) or build from source: + ```bash + 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` + + ```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: + +```bash +# 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09): + +```bash +# 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 may be provided in future. + +## 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. + +**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](https://github.com/MCP-UI-Org/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](https://github.com/block/goose)) will automatically render these HTML views. Clients without UI support (like [Claude Desktop](https://claude.ai/download) and [Claude Code](https://github.com/anthropics/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](https://hub.apps.edge.platform.mg3.mdb.osc.live) for all operations +* **EdgeConnect SDK**: Built on the [Go SDK](/docs/edgeconnect/edgeconnect-sdk/) for authentication and API client implementation +* **[MCP-UI](https://github.com/MCP-UI-Org/mcp-ui)**: All tools return dual-format responses (JSON + HTML). Clients that support UI resources (like [Goose](https://github.com/block/goose)) render rich HTML dashboards; others use the JSON data automatically. +* **[Claude Desktop](https://claude.ai/download)/[Code](https://github.com/anthropics/claude-code)**: Primary integration targets for AI-assisted infrastructure management +* **OAuth Providers**: Supports [Auth0](https://auth0.com/), [Amazon Cognito](https://aws.amazon.com/cognito/), [Keycloak](https://www.keycloak.org/), and other [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09)-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](/docs/edgeconnect/edgeconnect-client/) 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 + +## Status + +**Maturity**: Production + +## Additional Resources + +* [Model Context Protocol Specification](https://modelcontextprotocol.io/) +* [MCP-UI Documentation](https://github.com/MCP-UI-Org/mcp-ui) +* [EdgeConnect API Documentation](https://swagger.edge.platform.mg3.mdb.osc.live/) +* [Claude Desktop](https://claude.ai/download) +* [OAuth 2.1 RFC](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09) +* [Source Code Repository](https://edp.buildth.ing/DevFW-CICD/edge-connect-mcp)