Codesphere MCP Server

Der offizielle Codesphere MCP Server verbindet KI-Assistenten über das Model Context Protocol (MCP) mit dem Codesphere-Account. Nach der Konfiguration können Assistenten wie Claude, Cursor oder GitHub Copilot in VS Code Workspaces auflisten und erstellen, Pipeline-Stages ausführen, Logs lesen, Domains verwalten und vieles mehr – direkt aus einem Chat-Prompt.

Der MCP Server ist in die Codesphere CLI integriert und startet mit dem Befehl cs mcp. Es muss nichts zusätzlich installiert werden.

info

Der Codesphere MCP Server ist Open Source und Teil des cs-go-Repositories auf GitHub. Issues und Beiträge sind jederzeit willkommen.

Voraussetzungen

1. Codesphere CLI ab Version 1.2.0. Folge der CLI-Installationsanleitung und prüfe die Version mit cs version.
2. Ein Codesphere API-Token. Erstelle eines unter User Settings → API Keys, wie unter API-Schlüssel beschrieben.
3. Einen MCP-kompatiblen Client, zum Beispiel Claude Code, Claude Desktop, Cursor oder VS Code.

Token-Berechtigungen

API-Tokens sind persönliche Zugriffstoken. Der MCP Server kann alles ausführen, wozu auch der eigene Benutzeraccount berechtigt ist – einschließlich des Löschens von Workspaces, Resource Groups und Domains. Lasse die Bestätigungsaufforderungen deines Clients für Tool-Aufrufe aktiviert, damit jede Aktion vor der Ausführung bestätigt wird.

Konfiguration

Der Server kommuniziert mit dem Client über Standard-Ein-/Ausgabe (stdio). Der Client startet cs mcp als lokalen Prozess und übergibt die Konfiguration als Umgebungsvariablen:

Variable	Erforderlich	Beschreibung
CS_TOKEN	Ja	Das Codesphere API-Token.
CS_API	Nein	URL der Codesphere API. Standardmäßig wird die Enterprise Cloud API (https://cloud.codesphere.com/api) verwendet. Für jede andere Codesphere-Instanz, etwa eine Private Cloud-Installation, auf <codesphere-instance-url>/api setzen.

Resource Group- und Workspace-IDs sind nicht Teil der Konfiguration. Der Assistent übergibt sie bei jedem Tool-Aufruf und kann sie mit list_teams und list_workspaces ermitteln.

Server zum Client hinzufügen

Claude Code

Diesen Befehl im Terminal ausführen:

claude mcp add codesphere --env CS_TOKEN=your-api-token-here -- cs mcp

Mit --scope user wird der Server in allen Projekten verfügbar gemacht. Die Verbindung lässt sich mit /mcp innerhalb von Claude Code prüfen.

Claude Desktop

Settings → Developer → Edit Config öffnen und den Server in claude_desktop_config.json hinzufügen:

{
  "mcpServers": {
    "codesphere": {
      "command": "cs",
      "args": ["mcp"],
      "env": {
        "CS_TOKEN": "your-api-token-here"
      }
    }
  }
}

Anschließend Claude Desktop neu starten.

Cursor

Den Server in ~/.cursor/mcp.json hinzufügen, um ihn in allen Projekten zu nutzen, oder in .cursor/mcp.json, um ihn nur in einem Projekt zu verwenden:

{
  "mcpServers": {
    "codesphere": {
      "command": "cs",
      "args": ["mcp"],
      "env": {
        "CS_TOKEN": "your-api-token-here"
      }
    }
  }
}

VS Code

.vscode/mcp.json im Projekt erstellen. Mit dieser Konfiguration fragt VS Code das Token einmalig ab und speichert es sicher, sodass es nie im Repository landet:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "cs-token",
      "description": "Codesphere API token",
      "password": true
    }
  ],
  "servers": {
    "codesphere": {
      "type": "stdio",
      "command": "cs",
      "args": ["mcp"],
      "env": {
        "CS_TOKEN": "${input:cs-token}"
      }
    }
  }
}

Der Server wird über den Befehl MCP: List Servers gestartet; die Tools lassen sich im Agent-Modus von Copilot Chat verwenden.

Andere Clients

Jeder Client, der lokale stdio-MCP-Server unterstützt, funktioniert auf die gleiche Weise. Dabei cs als Befehl, mcp als Argument verwenden und CS_TOKEN in der Umgebung setzen.

Verfügbare Tools

Der Codesphere MCP Server stellt dem Assistenten die folgenden Tools zur Verfügung.

Workspaces

Tool	Beschreibung
list_workspaces	Listet alle Workspaces einer Resource Group auf.
get_workspace	Ruft die Details eines Workspace ab.
workspace_status	Ruft den Runtime-Status eines Workspace ab.
create_workspace	Erstellt einen Workspace, optional aus einem Git-Repository, Branch und Base-Image.
delete_workspace	Löscht einen Workspace.
set_workspace_env_var	Setzt Umgebungsvariablen für einen Workspace.
exec_command	Führt einen Befehl innerhalb eines Workspace aus und gibt dessen Ausgabe zurück.
scale_workspace	Ändert die Anzahl der Replicas eines Workspace.

Pipelines, Landscapes und Logs

Tool	Beschreibung
start_pipeline_stage	Startet eine CI-Pipeline-Stage (prepare, test oder run) für ein CI-Profil.
stop_pipeline_stage	Stoppt die laufende Pipeline-Stage.
get_pipeline_state	Ruft den Status einer Pipeline-Stage ab.
deploy_landscape	Deployt die Landscape eines Workspace für ein Profil.
scale_landscape_services	Legt die Replica-Anzahl einzelner Landscape-Services fest.
get_logs_of_stage	Ruft die Logs einer Pipeline-Stage ab.
get_logs_of_replica	Ruft die Logs eines bestimmten Server-Replicas ab.
get_logs_of_server	Ruft die Logs eines bestimmten Landscape-Servers ab.

Resource Groups

Tool	Beschreibung
list_teams	Listet alle Resource Groups auf, denen man angehört, optional gefiltert nach Organisation.
get_team	Ruft die Details einer Resource Group ab.
create_team	Erstellt eine Resource Group in einem Rechenzentrum.
delete_team	Löscht eine Resource Group.

Domains

Tool	Beschreibung
list_domains	Listet alle benutzerdefinierten Domains einer Resource Group auf.
get_domain	Ruft die Details einer Domain ab.
create_domain	Fügt einer Resource Group eine benutzerdefinierte Domain hinzu.
update_domain	Aktualisiert die Einstellungen einer Domain.
verify_domain	Löst die DNS-Verifizierung für eine Domain aus.
delete_domain	Löscht eine Domain.

Nutzung

Tool	Beschreibung
get_usage_summary_landscape	Ruft eine Nutzungsübersicht der Landscapes einer Resource Group für einen Zeitraum ab.
get_landscape_service_events	Ruft die Nutzungsereignisse eines Landscape-Service für einen Zeitraum ab.

Plattform-Metadaten

Tool	Beschreibung
list_data_centers	Listet die verfügbaren Rechenzentren auf.
list_workspace_plans	Listet die verfügbaren Workspace-Pläne auf.
list_base_images	Listet die verfügbaren Workspace-Base-Images auf.

Beispiel-Prompts

Von null zur laufenden App

Der Assistent kann die Tools miteinander verketten, um eine ganze Aufgabe abzuschließen, nicht nur einzelne Schritte. Zum Beispiel:

„Erstelle einen neuen Workspace namens docs-demo im kleinsten Plan, richte darin eine neue Docusaurus-Site ein, deploye sie und behebe Fehler, bis sie fehlerfrei läuft."

Um diesen Prompt umzusetzen, geht der Assistent typischerweise wie folgt vor:

1. Ermittelt die Resource Group und die verfügbaren Pläne mit list_teams und list_workspace_plans und erstellt anschließend den Workspace mit create_workspace.
2. Erstellt das Docusaurus-Projektgerüst und schreibt eine ci.yml mit prepare- und run-Stages mithilfe von exec_command.
3. Startet die prepare-Stage und anschließend die run-Stage mit start_pipeline_stage und prüft deren Fortschritt mit get_pipeline_state.
4. Schlägt eine Stage fehl, liest der Assistent die Ausgabe mit get_logs_of_stage, behebt die Ursache mit exec_command und startet die Stage erneut.
5. Bestätigt mit workspace_status, dass der Workspace läuft, und meldet das Ergebnis zurück.

tipp

Für solche Aufgaben sollten die Bestätigungsaufforderungen des Clients für Tool-Aufrufe aktiviert bleiben. So ist jeder Befehl sichtbar, bevor er im Workspace ausgeführt wird.

Kurze Aufgaben

Es lassen sich auch einzelne Aktionen anfragen, zum Beispiel:

• „Liste alle Workspaces in meiner Resource Group auf und zeige, welche davon laufen."
• „Erstelle einen Workspace namens my-api aus https://github.com/my-org/my-api, Branch main, im kleinsten Plan."
• „Führe die prepare-Stage und anschließend die run-Stage in Workspace 12345 aus und sag mir Bescheid, wenn er läuft."
• „Die run-Stage von Workspace 12345 schlägt fehl. Hol die Logs und finde heraus, woran es liegt."
• „Setze DATABASE_URL und NODE_ENV=production für Workspace 12345."
• „Füge meiner Resource Group die Domain app.example.com hinzu und verifiziere sie."
• „Wie hoch war die Landscape-Nutzung meiner Resource Group im letzten Monat?"

Fehlerbehebung

• CS_TOKEN env var required, but not set: Der Server findet das Token nicht. Prüfen, ob CS_TOKEN im Abschnitt env der Client-Konfiguration gesetzt ist, und den Client anschließend neu starten.
• Der Client findet den Befehl cs nicht: Desktop-Anwendungen laden oft nicht den PATH der Shell. In diesem Fall den absoluten Pfad zur Binärdatei als Befehl verwenden, zum Beispiel /usr/local/bin/cs. Mit which cs lässt sich der Pfad ermitteln. Unter Windows den vollständigen Pfad zu cs.exe verwenden.
• Authentifizierungsfehler bei Tool-Aufrufen: Das Token wurde möglicherweise widerrufen, oder CS_API verweist auf die falsche Codesphere-Instanz.
• Tools fehlen oder sind veraltet: Die CLI mit cs update aktualisieren und den Client neu starten.

Eine Referenz zum Befehl selbst liefert cs mcp --help oder die CLI-Befehlsreferenz.