Cloud Harness MCP

Cloud Harness MCP is an MIT-licensed remote coding harness exposed through authenticated Streamable HTTP MCP. It opens an isolated clone in a TTL-limited Docker executor and gives one trusted owner structured workspace, file, code-intelligence, command, shell, session, dependency-task, Git, worktree, skill, hook, memory, and repository-defined deployment tools.

The public MCP URL is:

https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp

Architecture

MCP is the northbound control protocol; the harness is the execution runtime. The split keeps Internet-facing request handling away from Docker authority and keeps repository credentials out of long-lived executors.

flowchart LR
  Client["AI coding client"] -->|"HTTPS · MCP bearer"| Nginx["nginx + loopback ingress"]

  subgraph Control["Trusted control plane"]
    Nginx --> API["Stateless MCP API"]
    API -->|"private authenticated RPC"| Runner["Runner · policy · lifecycle"]
    Runner --> Store[("SQLite workspace state")]
    Runner --> Docker["Docker authority"]
    Runner --> Broker["GitHub App broker"]
  end

  subgraph Execution["TTL-bound execution plane"]
    Docker --> Executor["Non-root workspace executor"]
    Docker --> GitHelper["Ephemeral Git transfer helper"]
    Executor --> Repo[("Isolated repository clone")]
  end

  Broker -->|"short-lived token over stdin"| GitHelper
  GitHelper -->|"validated HTTPS origin"| GitHub["GitHub repository"]
  Executor -.->|"no control-plane credential"| GitHub

The source of truth for these boundaries is compose.yaml, apps/runner/src/workspace-service.ts, and the security model.

Related MCP server: Coding Tools MCP

Coding workflow

sequenceDiagram
  participant C as AI client
  participant A as MCP API
  participant R as Runner
  participant E as Isolated executor
  participant G as Ephemeral Git helper
  participant H as GitHub

  C->>A: workspace_open(repositoryUrl, idempotencyKey)
  A->>R: authenticated operation
  R->>G: constrained clone + optional short-lived token
  G->>H: credential-free or GitHub App HTTPS clone
  R->>E: start bounded workspace container
  R-->>C: opaque workspaceId
  C->>E: inspect, edit, test, session, task graph, commit
  C->>R: git_push(refspec, forceWithLease?, expectedRemoteOid?)
  R->>G: stage clean bare transfer + short-lived token
  G->>H: origin-only push
  G-->>R: bounded sanitized result
  R-->>C: structured MCP result
  C->>R: workspace_close(workspaceId)
  R->>E: terminate and remove

Remote fetch, pull, and push use a sibling transfer repository that the executor cannot see. Push requires a GitHub App installation with repository write access; clone/fetch/pull need read access. See configuration and MCP semantics.

Connect from AI clients

This server exposes a remote Streamable HTTP MCP endpoint:

https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp

All direct integrations below use the owner-provided CLOUD_HARNESS_MCP_TOKEN. Keep it in a local environment variable or client-local configuration; never put it in a repository, prompt, or shared project configuration. This is a single-owner execution service: granting a client access grants it the ability to ask the executor to run commands. Read the security model before connecting it.

ChatGPT custom MCP apps are configured in the web app and must be reachable from OpenAI's infrastructure. Enable Developer mode, then go to Settings or Workspace settings → Apps → Create, enter the endpoint above, scan its tools, and create the app. The exact availability and controls depend on the ChatGPT plan and workspace role; follow OpenAI's current Developer mode guide.

This deployment uses a static bearer token. ChatGPT's custom-app flow is intended for supported authentication flows such as OAuth and does not provide a documented place to supply an arbitrary Authorization header. Put an OAuth-capable MCP gateway in front of the service before connecting it to ChatGPT; do not place the owner bearer token in an app definition or a chat.

Set the token in your shell before starting Codex:

export CLOUD_HARNESS_MCP_TOKEN="<owner-provided-token>"

On PowerShell, use:

$env:CLOUD_HARNESS_MCP_TOKEN = "<owner-provided-token>"

Add this to ~/.codex/config.toml (or a trusted project's .codex/config.toml):

[mcp_servers.cloud_harness]
url = "https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp"
bearer_token_env_var = "CLOUD_HARNESS_MCP_TOKEN"
required = true
tool_timeout_sec = 300
default_tools_approval_mode = "writes"

Restart Codex, then use /mcp or codex mcp list to confirm the connection. The fields follow the Codex MCP configuration documentation.

Claude's remote custom connectors are set up from the Claude app and are called from Anthropic's cloud, rather than from your computer. In Settings → Connectors, add the public endpoint and complete the connector's supported authentication flow. The current workflow and plan availability are documented by Anthropic.

The hosted connector flow is OAuth-oriented and has no documented static-header field. Therefore this bearer-token deployment cannot be connected directly to Claude Desktop. Use an OAuth-capable gateway in front of it, or use Claude Code below, which supports a local Authorization header.

Set the token, then register the server for your user account:

export CLOUD_HARNESS_MCP_TOKEN="<owner-provided-token>"
claude mcp add --transport http --scope user \
  --header "Authorization: Bearer $CLOUD_HARNESS_MCP_TOKEN" \
  cloud-harness https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp

Use claude mcp get cloud-harness to inspect the entry, then /mcp in a Claude Code session to confirm that it is available. Claude Code documents remote HTTP registration and static headers in its MCP guide.

Set the token, then add a remote HTTP MCP server:

export CLOUD_HARNESS_MCP_TOKEN="<owner-provided-token>"
gemini mcp add --transport http \
  --header "Authorization: Bearer $CLOUD_HARNESS_MCP_TOKEN" \
  cloud-harness https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp

Restart Gemini CLI if it is already running and use its MCP management command to confirm the server. See the Gemini CLI MCP-server reference for the supported transports and header syntax.

Open Customize → MCP and add a remote Streamable HTTP server, or add the following to the global ~/.cursor/mcp.json (use .cursor/mcp.json for a trusted project only):

{
  "mcpServers": {
    "cloud-harness": {
      "url": "https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:CLOUD_HARNESS_MCP_TOKEN}"
      }
    }
  }
}

Restart Cursor, approve the server, and check that cloud-harness appears in the chat's available tools. Cursor documents the configuration locations and remote MCP support in its MCP guide. The global file is user-local; do not copy the token-bearing project file into source control.

In the agent side panel, choose … → MCP Servers → Manage MCP Servers → View raw config. This opens the global ~/.gemini/config/mcp_config.json; add a remote server entry:

{
  "mcpServers": {
    "cloud-harness": {
      "serverUrl": "https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp",
      "headers": {
        "Authorization": "Bearer <owner-provided-token>"
      }
    }
  }
}

Save the file and confirm that the server is enabled in the MCP Servers panel. Antigravity's MCP reference defines the global path, serverUrl, and headers for remote MCP servers. Keep this local configuration private.

In Grok web, open the + menu, choose Connectors, then select Add connector to create a custom MCP connection. It must use a public URL; see xAI's connector overview. The consumer connector UI may require an OAuth flow, so it is not a documented direct path for this static bearer-token service.

For the xAI API, Remote MCP Tools support an explicit authorization token. Add this object to a Responses API request's tools array:

{
  "type": "mcp",
  "server_url": "https://cloud-harness-mcp.46-250-239-227.sslip.io/mcp",
  "server_label": "cloud-harness",
  "authorization": "Bearer <owner-provided-token>"
}

Limit allowed_tools when the request needs only a subset. The xAI Remote MCP Tools reference documents Streamable HTTP support, authorization, and tool allowlisting.

Start by asking a connected client to call workspace_open with a credential-free HTTPS repository URL and a new idempotency key. Reuse the returned opaque workspaceId for later calls and finish with workspace_close. See MCP usage for the workflow and important semantics.

Run locally

Prerequisites are Node.js 24+, npm, Docker Engine, and Docker Compose v2.

npm ci
cp .env.example .env
# Replace every change-me value in .env with an independent random secret.
docker compose --profile images build executor-image api runner
docker compose up -d runner api ingress
curl --fail http://127.0.0.1:3100/readyz

Local Compose publishes only a credential-free TCP ingress proxy on host loopback. The API and runner remain on separate internal networks; only the runner has Docker authority. Local Compose does not configure TLS. Stop it with:

docker compose down

Documentation

• Project-local cloudharness agent skill

• System architecture

• MCP usage and tool semantics

• Configuration

• Security model

• Development and testing

• Operations, backup, rollback, and cleanup

• VPS deployment with nginx and Certbot

• Cloudflare Pages landing page

• Troubleshooting

The repository is public at bestagentkits/cloud-harness-mcp and licensed under the MIT License.