Codesphere MCP Server

The official Codesphere MCP server connects AI assistants to your Codesphere account through the Model Context Protocol (MCP). Once it is configured, assistants like Claude, Cursor or GitHub Copilot in VS Code can list and create workspaces, run pipeline stages, read logs, manage domains and more, all from a chat prompt.

The MCP server is built into the Codesphere CLI and starts with the cs mcp command. There is nothing extra to install.

info

The Codesphere MCP server is open-source and part of the cs-go repository on GitHub. Feel free to open issues or contribute.

Prerequisites

1. Codesphere CLI v1.2.0 or later. Follow the CLI installation guide and check your version with cs version.
2. A Codesphere API token. Create one under User Settings → API Keys, as described in API keys.
3. An MCP-compatible client, such as Claude Code, Claude Desktop, Cursor or VS Code.

Token permissions

API tokens are personal access tokens. The MCP server can do everything your user account can do, including deleting workspaces, teams and domains. Keep your client's tool approval prompts turned on so you confirm each action before it runs.

Configuration

The server talks to your client over standard input/output (stdio). Your client starts cs mcp as a local process and passes the configuration as environment variables:

Variable	Required	Description
CS_TOKEN	Yes	Your Codesphere API token.
CS_API	No	URL of the Codesphere API. Defaults to the Enterprise Cloud API (https://cloud.codesphere.com/api). For any other Codesphere instance, such as a Private Cloud installation, set it to <codesphere-instance-url>/api.

Team and workspace IDs are not part of the configuration. The assistant passes them with each tool call, and can look them up with list_teams and list_workspaces.

Add the server to your client

Claude Code

Run this command in your terminal:

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

Add --scope user to make the server available in all your projects. Check the connection with /mcp inside Claude Code.

Claude Desktop

Open Settings → Developer → Edit Config and add the server to claude_desktop_config.json:

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

Restart Claude Desktop afterwards.

Cursor

Add the server to ~/.cursor/mcp.json to use it in all projects, or to .cursor/mcp.json to use it in one project:

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

VS Code

Create .vscode/mcp.json in your project. With this configuration VS Code prompts for the token once and stores it securely, so it never ends up in your repository:

{
  "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}"
      }
    }
  }
}

Start the server from the MCP: List Servers command and use the tools in Copilot Chat's agent mode.

Other clients

Any client that supports local stdio MCP servers works the same way. Use cs as the command, mcp as the argument, and set CS_TOKEN in the environment.

Available tools

The Codesphere MCP server provides the following tools to your assistant.

Workspaces

Tool	Description
list_workspaces	List all workspaces of a team.
get_workspace	Get the details of a workspace.
workspace_status	Get the runtime status of a workspace.
create_workspace	Create a workspace, optionally from a Git repository, branch and base image.
delete_workspace	Delete a workspace.
set_workspace_env_var	Set environment variables on a workspace.
exec_command	Run a command inside a workspace and return its output.
scale_workspace	Change the number of replicas of a workspace.

Pipelines, landscapes and logs

Tool	Description
start_pipeline_stage	Start a CI pipeline stage (prepare, test or run) for a CI profile.
stop_pipeline_stage	Stop the running pipeline stage.
get_pipeline_state	Get the status of a pipeline stage.
deploy_landscape	Deploy the landscape of a workspace for a profile.
scale_landscape_services	Set the replica count of individual landscape services.
get_logs_of_stage	Get the logs of a pipeline stage.
get_logs_of_replica	Get the logs of a specific server replica.
get_logs_of_server	Get the logs of a specific landscape server.

Teams

Tool	Description
list_teams	List all teams you belong to, optionally filtered by organization.
get_team	Get the details of a team.
create_team	Create a team in a data center.
delete_team	Delete a team.

Domains

Tool	Description
list_domains	List all custom domains of a team.
get_domain	Get the details of a domain.
create_domain	Add a custom domain to a team.
update_domain	Update the settings of a domain.
verify_domain	Trigger DNS verification for a domain.
delete_domain	Delete a domain.

Usage

Tool	Description
get_usage_summary_landscape	Get a usage summary of a team's landscapes for a time range.
get_landscape_service_events	Get the usage events of a landscape service for a time range.

Platform metadata

Tool	Description
list_data_centers	List the available data centers.
list_workspace_plans	List the available workspace plans.
list_base_images	List the available workspace base images.

Example prompts

From zero to a running app

The assistant can chain the tools to complete a whole task, not just single steps. For example:

"Create a new workspace called docs-demo on the smallest plan, bootstrap a new Docusaurus site in it, deploy it and debug until it's healthy."

To complete this prompt, the assistant typically:

1. Looks up your team and the available plans with list_teams and list_workspace_plans, then creates the workspace with create_workspace.
2. Scaffolds the Docusaurus project and writes a ci.yml with prepare and run stages using exec_command.
3. Starts the prepare stage and then the run stage with start_pipeline_stage, and checks their progress with get_pipeline_state.
4. If a stage fails, reads the output with get_logs_of_stage, fixes the cause with exec_command and starts the stage again.
5. Confirms with workspace_status that the workspace is running and reports back.

tip

Keep your client's tool approval prompts turned on for tasks like this. You see each command before it runs inside your workspace.

Quick tasks

You can also ask for single actions, such as:

• "List all workspaces in my team and show which ones are running."
• "Create a workspace called my-api from https://github.com/my-org/my-api, branch main, on the smallest plan."
• "Run the prepare stage and then the run stage in workspace 12345, and tell me when it's up."
• "The run stage of workspace 12345 is failing. Get the logs and figure out why."
• "Set DATABASE_URL and NODE_ENV=production on workspace 12345."
• "Add the domain app.example.com to my team and verify it."
• "How much landscape usage did my team have last month?"

Troubleshooting

• CS_TOKEN env var required, but not set: The server can't find your token. Check that CS_TOKEN is set in the env section of your client's configuration, then restart the client.
• The client can't find the cs command: Desktop apps often don't load your shell's PATH. Use the absolute path to the binary as the command, for example /usr/local/bin/cs. Run which cs to find it. On Windows, use the full path to cs.exe.
• Authentication errors from tool calls: Your token may have been revoked, or CS_API may point to the wrong Codesphere instance.
• Tools are missing or outdated: Update the CLI with cs update and restart your client.

For a reference of the command itself, run cs mcp --help or see the CLI command reference.