Codesphere MCP Server

The first MCP server for Codesphere. It connects Claude to the Codesphere platform, letting you deploy, manage, and monitor workspaces directly from a conversation. No API keys to configure, no self-hosting required — just connect and go.

Quick Start

1. Open claude.ai → Settings → Integrations
2. Click Add Integration
3. Paste: https://codesphere-mcp.therediyeteam.workers.dev/mcp
4. Enter your Codesphere API key when prompted
5. Done — try asking Claude: "List my Codesphere workspaces"

Your API key is stored encrypted in your personal OAuth session. It is never shared with other users or stored in plaintext.

Available Tools

Tool	Description	Key Parameters
list_workspaces	List all workspaces for a team with their status, URL, and git info	teamId (optional)
get_workspace_status	Get detailed status including pipeline state for all stages	workspaceId
workspace_summary	Get everything at once: status, git, env vars, pipeline state	workspaceId
create_workspace	Create a new workspace from a git repository	gitUrl, name, planId, branch
clone_workspace	Duplicate a workspace (same repo, settings, env vars)	sourceWorkspaceId, name
delete_workspace	Permanently delete a workspace	workspaceId
deploy	Pull latest code and run full CI pipeline (git pull, prepare, run)	workspaceId, skipPrepare, waitForPrepare
stop_workspace	Stop a running workspace	workspaceId
restart_workspace	Restart without rebuilding (stop, start)	workspaceId
scale_workspace	Scale a workspace by changing the number of replicas	workspaceId, replicas
deploy_landscape	Deploy a multi-service landscape	workspaceId, profile (optional)
teardown_landscape	Tear down a running landscape	workspaceId
execute_command	Run a shell command in a workspace	workspaceId, command
set_env_vars	Set environment variables on a workspace	workspaceId, envVars
list_env_vars	List all environment variables on a workspace	workspaceId
git_info	Get current git HEAD info (branch, commit)	workspaceId
view_logs	Get recent logs from a pipeline stage	workspaceId, stage, lines
list_domains	List all custom domains for a team	teamId (optional)
create_domain	Register a new custom domain	domainName, teamId (optional)
delete_domain	Remove a custom domain	domainName, teamId (optional)
verify_domain	Verify DNS configuration for a domain	domainName, teamId (optional)
switch_domain	Route a custom domain to a different workspace	domainName, workspaceId, path

Example Conversations

• "List my Codesphere workspaces" — shows all workspaces with their status, URLs, and git info.
• "Deploy workspace 12345" — pulls the latest code, builds, and starts the workspace.
• "Create a new workspace from github.com/user/repo and deploy it" — creates and deploys a workspace.
• "Show me the logs for workspace 12345" — retrieves recent log output from the run stage.
• "Switch my production domain to point to workspace 12346" — re-routes a custom domain for zero-downtime releases.

How It Works

The server runs on Cloudflare Workers with per-user OAuth 2.1 authentication:

Claude.ai ←→ OAuth 2.1 (PKCE) ←→ Cloudflare Worker
                                        │
                                   OAuthProvider
                                        │
                               ┌────────┴────────┐
                               │                  │
                          /authorize          /mcp (McpAgent)
                          (key form)          (tools)
                               │                  │
                          Validate key        Per-user token
                          via Codesphere API  → Codesphere API

Each user authenticates with their own API key. Keys are encrypted in individual OAuth sessions — never stored in plaintext, never shared between users.

Deploy Your Own Instance

Want to run your own? It takes 5 minutes:

Prerequisites

• Cloudflare account (free tier works)
• Node.js 18+

Steps

git clone https://github.com/LeonHartmann/codesphere-mcp.git
cd codesphere-mcp
npm install

# Login to Cloudflare
npx wrangler login

# Create KV namespace for OAuth sessions
npx wrangler kv namespace create OAUTH_KV
# Say yes when it asks to update wrangler.jsonc

# Set the cookie encryption secret
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY

# Deploy
npx wrangler deploy

Your server will be live at https://codesphere-mcp.<your-subdomain>.workers.dev.

Local Development

npx wrangler dev

Starts on http://localhost:8787. Use the MCP Inspector to test interactively.

Companion Skill

If you use Claude Code, check out the companion skill at github.com/LeonHartmann/codesphere-skill for direct CLI integration.

License

MIT