Codesphere MCP Server

Der offizielle Codesphere MCP Server verbindet KI-Assistenten über das Model Context Protocol (MCP) mit dem Codesphere-Konto. 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 über einen Chat-Prompt.

Der MCP Server ist in die Codesphere CLI integriert und startet mit dem Befehl cs mcp. Es muss nichts Zusätzliches 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 v1.2.0 oder neuer. 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 Keys beschrieben.
3. Ein MCP-kompatibler Client, zum Beispiel Claude Code, Claude Desktop, Cursor oder VS Code.

Token-Berechtigungen

API-Tokens sind persönliche Zugriffstoken. Der MCP Server kann alles tun, wozu auch das eigene Benutzerkonto in der Lage ist, einschließlich des Löschens von Workspaces, Teams und Domains. Lasse die Bestätigungsabfragen des Clients aktiviert, damit jede Aktion vor der Ausführung bestätigt wird.

Konfiguration

Der Server kommuniziert mit dem Client über Standardein-/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 die Enterprise Cloud API (https://cloud.codesphere.com/api). Für jede andere Codesphere-Instanz, zum Beispiel eine Private Cloud-Installation, auf <codesphere-instance-url>/api setzen.

Team- 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 nachschlagen.

Server zum Client hinzufügen

Claude Code

Führe diesen Befehl im Terminal aus:

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

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

Claude Desktop

Öffne Settings → Developer → Edit Config und füge den Server zu claude_desktop_config.json hinzu:

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

Anschließend Claude Desktop neu starten.

Cursor

Füge den Server zu ~/.cursor/mcp.json hinzu, um ihn in allen Projekten zu nutzen, oder zu .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

Erstelle .vscode/mcp.json im Projekt. Mit dieser Konfiguration fragt VS Code einmalig nach dem Token und speichert ihn sicher, sodass er 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}"
      }
    }
  }
}

Starte den Server über den Befehl MCP: List Servers und nutze die Tools im Agent-Modus von Copilot Chat.

Andere Clients

Jeder Client, der lokale stdio-MCP-Server unterstützt, funktioniert auf dieselbe Weise. Verwende cs als Befehl, mcp als Argument und setze CS_TOKEN in der Umgebung.

Verfügbare Tools

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

Workspaces

Tool	Beschreibung
list_workspaces	Listet alle Workspaces eines Teams auf.
get_workspace	Ruft die Details eines Workspace ab.
workspace_status	Ruft den Laufzeitstatus 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	Setzt die Replica-Anzahl einzelner Landscape-Services.
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.

Teams

Tool	Beschreibung
list_teams	Listet alle Teams auf, denen du angehörst, optional gefiltert nach Organisation.
get_team	Ruft die Details eines Teams ab.
create_team	Erstellt ein Team in einem Rechenzentrum.
delete_team	Löscht ein Team.

Domains

Tool	Beschreibung
list_domains	Listet alle benutzerdefinierten Domains eines Teams auf.
get_domain	Ruft die Details einer Domain ab.
create_domain	Fügt einem Team 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 eines Teams für einen Zeitraum ab.
get_landscape_service_events	Ruft die Nutzungsereignisse eines Landscape-Services 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 verketten, um eine ganze Aufgabe zu erledigen, nicht nur einzelne Schritte. Zum Beispiel:

„Erstelle einen neuen Workspace namens docs-demo im kleinsten Plan, bootstrape darin eine neue Docusaurus-Seite, deploye sie und debugge, bis sie fehlerfrei läuft."

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

1. Ermittelt das Team 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. Falls eine Stage fehlschlägt, liest 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

Lasse die Bestätigungsabfragen des Clients für Aufgaben wie diese aktiviert. So wird jeder Befehl angezeigt, bevor er im Workspace ausgeführt wird.

Schnelle Aufgaben

Es lassen sich auch einzelne Aktionen anfragen, zum Beispiel:

• „Liste alle Workspaces in meinem Team 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 dann die Run-Stage in Workspace 12345 aus und sag mir, wenn er läuft."
• „Die Run-Stage von Workspace 12345 schlägt fehl. Hole die Logs und finde heraus, warum."
• „Setze DATABASE_URL und NODE_ENV=production für Workspace 12345."
• „Füge meinem Team die Domain app.example.com hinzu und verifiziere sie."
• „Wie hoch war die Landscape-Nutzung meines Teams im letzten Monat?"

Fehlerbehebung

• CS_TOKEN env var required, but not set: Der Server findet den Token nicht. Prüfe, ob CS_TOKEN im Abschnitt env der Client-Konfiguration gesetzt ist, und starte den Client neu.
• Der Client findet den Befehl cs nicht: Desktop-Apps laden oft nicht die PATH-Variable der Shell. Verwende den absoluten Pfad zur Binary als Befehl, zum Beispiel /usr/local/bin/cs. Mit which cs lässt er sich ermitteln. Unter Windows den vollständigen Pfad zu cs.exe verwenden.
• Authentifizierungsfehler bei Tool-Aufrufen: Der 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 des Befehls selbst findet sich über cs mcp --help oder in der CLI-Befehlsreferenz.