Cloud Harness Mcp

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 a trusted owner or named mutually trusted operators structured workspace, file, code-intelligence, command, shell, session, dependency-task, Git, worktree, skill, hook, memory, and repository-defined deployment tools.

> [!WARNING] > This is a private service for one security domain. Its operators must trust > one another because it is intentionally capable of arbitrary command > execution inside a shared-kernel executor. Principal isolation is not a > hostile multi-tenant sandbox. Read the [security model](docs/security-model.md) > before operating it.

The Managed OAuth MCP URL is:

https://harness.zuey.me/mcp

Static-header clients use dashboard-managed API keys at the separate gateway:

https://api.harness.zuey.me/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
  OAuthClient["Managed OAuth client"] -->|"Access OAuth"| Nginx["nginx + loopback ingress"]
  StaticClient["Static-header client"] -->|"managed API key"| Gateway["Cloudflare Worker gateway"]
  Gateway -->|"Access service assertion + API key"| Nginx

  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](compose.yaml), [apps/runner/src/workspace-service.ts](apps/runner/src/workspace-service.ts), and the [security model](docs/security-model.md).

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](docs/configuration.md#optional-github-app-repository-access) and [MCP semantics](docs/mcp-api.md).

Getting started

1. Read the [security model](docs/security-model.md), then configure one of the

supported clients below with the owner token kept in local private configuration.

1. Ask the client to call workspace_open with a credential-free HTTPS

repository URL and a fresh idempotency key. Keep the returned opaque workspaceId; do not derive it from a path or repository name.

1. Use the bounded tools in the existing workspace, then close shells,

sessions, and unwanted tasks before calling workspace_close.

Start with the normal workflow in [MCP usage](docs/mcp-api.md#normal-workflow) for lifecycle, cursor, network, and Git-transfer semantics.

Local stdio workspace mode

In addition to the remote HTTP/Docker service, Cloud Harness MCP can operate directly against an explicitly selected project folder on your local machine over stdio transport.

# Start local stdio server for a project:
cloud-harness-mcp --transport stdio --workspace /path/to/project

In local mode:

• The configured folder behaves as an already-opened workspace (with an opaque workspaceId). workspace_open is not required.
• File operations, patches, grep search, symbol search, sessions, tasks, and local Git tools operate directly on the folder.
• workspace_close terminates owned child processes and tasks but never deletes your local project folder.
• Tool paths and working directories are strictly confined within the workspace root.
• Commands (exec_run, shells, tasks) execute with host-user permissions. File path confinement is not an OS sandbox.
• Network Git (git_fetch, git_pull) and Git push (git_push) are disabled by default and require explicit startup opt-in flags (--git-network, --git-push).
• v1 supports POSIX (Linux and macOS); Windows process semantics are a documented follow-up (use WSL on Windows).

CLI options

| Option | Description | |---|---| | --transport | Select transport protocol: http (default) or stdio | | --workspace | Absolute path to the local project folder (required for stdio) | | --git-network | Enable network Git operations (git_fetch, git_pull) | | --git-push | Enable Git push (git_push, implies --git-network) | | --env | Forward additional host environment variable (repeatable) | | -h, --help | Display help message | | -v, --version | Display version information |

Configuring local stdio in AI clients

Claude Desktop

In ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or ~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "cloud-harness-local": {
      "command": "node",
      "args": [
        "/path/to/cloud-harness-mcp/apps/api/dist/index.js",
        "--transport",
        "stdio",
        "--workspace",
        "/path/to/my-project"
      ]
    }
  }
}

Claude Code

claude mcp add cloud-harness-local --transport stdio -- node /path/to/cloud-harness-mcp/apps/api/dist/index.js --transport stdio --workspace /path/to/my-project

Cursor

In .cursor/mcp.json:

{
  "mcpServers": {
    "cloud-harness-local": {
      "command": "node",
      "args": [
        "/path/to/cloud-harness-mcp/apps/api/dist/index.js",
        "--transport",
        "stdio",
        "--workspace",
        "/path/to/my-project"
      ]
    }
  }
}

OpenAI Codex

In ~/.codex/config.toml:

[mcp_servers.cloud_harness_local]
command = "node"
args = ["/path/to/cloud-harness-mcp/apps/api/dist/index.js", "--transport", "stdio", "--workspace", "/path/to/my-project"]

MCP tools

The public tool names are owned by [RunnerOperationSchema](packages/contracts/src/runner-api.ts). Inputs, bounds, and approval annotations are owned by [TOOL_SPECS](packages/contracts/src/tool-schemas.ts); the API registers each of those specs in [mcp-server.ts](apps/api/src/mcp-server.ts).

Workspace lifecycle

workspace_open, workspace_list, workspace_status, workspace_capabilities, workspace_lease_renew, workspace_recover, workspace_context, workspace_set_active, workspace_close, secrets_list

Files and code intelligence

files_list, files_read, files_write, files_write_batch, files_apply_patch, files_delete, files_move, files_mkdir, grep_search, symbols_search, symbols_references

Commands, shells, sessions, and tasks

exec_run, shell_open, shell_io, shell_close, sessions_list, sessions_open, sessions_io, sessions_close, tasks_list, tasks_run, tasks_status, tasks_cancel, tasks_graph, operation_status, operation_cancel, operation_wait

Git and worktrees

git_status, git_diff, git_log, git_branch, git_checkout, git_add, git_commit, git_identity_status, git_identity_set, workspace_finalize, git_fetch, git_pull, git_push, git_merge, git_rebase, worktrees_list, worktrees_create, worktrees_remove, github_action

Repository extensions

skills_list, skills_read, skills_run, hooks_list, hooks_run, memories_list, memories_read, memories_write, deployments_list, deployments_run

Retained artifacts

artifacts_snapshot, artifacts_list, artifacts_read, artifacts_restore, artifacts_delete

Install the Cloud Harness skill

Install the self-contained cloudharness operating skill directly from this repository with the skills CLI:

npx skills add bestagentkits/cloud-harness-mcp --skill cloudharness

Use --global to install it for the current user instead of the current project. The skill includes detailed, portable references for every public operation, input bound, side effect, recovery path, and security boundary. It does not install credentials or connect the MCP endpoint; complete one of the client configurations below separately.

This repository also publishes the same skill as a plugin package for both Claude Code and OpenAI's plugin format.

Install from the Claude Code marketplace

claude plugin marketplace add bestagentkits/cloud-harness-mcp
claude plugin install cloud-harness@bestagentkits

The package is skills-only, so register the authenticated MCP connection under Claude Code below after installation. See Anthropic's plugin marketplace guide for update and uninstall commands.

Install from the OpenAI plugin marketplace

Once this repository has been added to an available OpenAI marketplace, install the package with:

codex plugin marketplace add bestagentkits/cloud-harness-mcp
codex plugin add cloud-harness@bestagentkits

The OpenAI package contains the portable skill, store metadata, logo, privacy policy, and terms. It intentionally does not embed an app registration ID, bearer token, or MCP authorization. OpenAI reviews skills-only and MCP-only plugins, but a public authenticated remote MCP listing requires a supported OAuth flow. The owner deployment uses Cloudflare Access Managed OAuth; the package itself still embeds no deployment-specific authorization or app registration. See OpenAI's plugin packaging, submission, and authentication guidance.

Connect from AI clients

The owner deployment exposes two remote Streamable HTTP MCP lanes:

Managed OAuth: https://harness.zuey.me/mcp
Static API key: https://api.harness.zuey.me/mcp

The owner deployment uses cloudflare-access: Managed OAuth clients connect to the first URL and complete GitHub or Google login in the browser. Static-header clients use only the second URL with Authorization: Bearer . Its dashboard is https://harness.zuey.me/dashboard.

Create, list, and revoke API keys under Dashboard → API keys. A new key is shown once and cannot be recovered; store it only in the client's private credential store. Keys expire after 1–3,650 days (approximately 10 years), and each identity may have at most 10 active keys. There are no per-tool scopes or rotation endpoint: replace a key by creating a new one and then revoking the old one. Every key has the creator's full MCP authority, including arbitrary command execution in the executor. Revocation or expiry denies the next request.

The API-key gateway is not an alternate dashboard login and does not accept Managed OAuth. Conversely, https://harness.zuey.me/mcp does not accept a dashboard-managed API key. See the [security model](docs/security-model.md) for the independent Worker/Access/key checks.

owner-bearer remains the software default for separate private deployments. The direct-header examples below use CLOUD_HARNESS_MCP_TOKEN. For this owner deployment, set it to a dashboard-managed key and use https://api.harness.zuey.me/mcp. For a separate owner-bearer deployment, use the owner-provided token and https:///mcp. Keep the credential and URL in client-local private configuration; never put the token in a repository, prompt, or shared project configuration.

Other operators may deploy cloudflare-access on an eligible hostname in an owned Cloudflare zone. Access provides Managed OAuth and GitHub/Google SSO; Cloud Harness verifies the forwarded assertion and exposes the dashboard at /dashboard. Treat client login as supported only after the exact client, Access policy, discovery, refresh, and revocation flow has been verified live. Implementation, merge, and Cloudflare configuration are separate evidence states. See [configuration](docs/configuration.md#authentication-and-request-policy) and [deployment](docs/deployment.md#cloudflare-access-rollout).

Granting either form of access grants remote execution authority. Read the [security model](docs/security-model.md) before connecting it.

ChatGPT

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. Initially, the connector is in Draft (Dev) state and can be tested in standard 1-on-1 ChatGPT Web chats with Developer Mode enabled. To enable access across team members without Developer Mode constraints, a Workspace Admin/Owner can publish the connector under Workspace settings → Apps → Drafts → Publish. The exact availability and controls depend on the ChatGPT plan (Business, Enterprise, or Edu beta for full MCP actions) and workspace role; follow OpenAI's current Developer mode guide and the ChatGPT Configuration Guide.

The owner-bearer mode is not a documented direct path because the custom-app flow has no arbitrary-header field. In cloudflare-access mode, use the owner-controlled Access URL and complete its OAuth flow; keep the connection provisional until the live compatibility checklist passes. Never place the owner bearer in an app definition or a chat. If invocation fails with FORBIDDEN: This conversation does not support developer MCPs, consult the Troubleshooting Guide.

Codex

Set the token in your shell before starting Codex:

export CLOUD_HARNESS_MCP_TOKEN=""

On PowerShell, use:

$env:CLOUD_HARNESS_MCP_TOKEN = ""

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

[mcp_servers.cloud_harness]
url = "https:///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 Desktop app

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](https://support.claude.com/en/articles/11175166-

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bestagentkits
• Source: bestagentkits/cloud-harness-mcp
• License: MIT
• Homepage: https://harness.agentkit.best/

Install and usage instructions live in the source repository linked above.