MCP server#

TaskCloud provides a Model Context Protocol server. With it, an agent such as Claude Code, Claude Desktop, Cursor or Codex can create sandboxes, run commands, edit files, expose ports and drive a desktop, with no glue code.

Every mode calls the public REST API, so each tool call is subject to the scopes of the API key you use. The hosted endpoint runs the same server as the self-hosted HTTP mode; it is not live yet. During the private beta @taskcloud/mcp is shared with beta participants directly; publication on npm is coming soon.

Use a restricted key#

Don't give an agent your admin key. Create a key limited to sandbox work and, optionally, to sandboxes with a given label:

curl -X POST https://api.task.cloud/v1/api-keys \
  -H "Authorization: Bearer $TASKCLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mcp-agent", "preset": "full-sandbox", "restrict": {"labels": {"owner": "mcp"}}, "expires_in_days": 30}'

Sandboxes created with this key automatically receive the label owner=mcp, and the key can only see and act on sandboxes with that label.

Setup#

Claude Code#

Local (stdio):

claude mcp add taskcloud --env TASKCLOUD_API_KEY=$TASKCLOUD_API_KEY -- npx -y @taskcloud/mcp

Remote (Streamable HTTP), against your own server or, once it is live, the hosted endpoint:

claude mcp add --transport http taskcloud http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer $TASKCLOUD_API_KEY"

# hosted (beta, coming soon)
claude mcp add --transport http taskcloud https://mcp.task.cloud/mcp \
  --header "Authorization: Bearer $TASKCLOUD_API_KEY"

Claude Desktop / Cursor#

Add the local server to the client's MCP configuration (claude_desktop_config.json, or .cursor/mcp.json):

{
  "mcpServers": {
    "taskcloud": {
      "command": "npx",
      "args": ["-y", "@taskcloud/mcp"],
      "env": { "TASKCLOUD_API_KEY": "taskcloud_sk_..." }
    }
  }
}

Cursor can also connect to an HTTP server with a static header:

{
  "mcpServers": {
    "taskcloud": {
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer taskcloud_sk_..." }
    }
  }
}

Claude Desktop's remote connectors sign in with OAuth, which the HTTP mode does not support yet (see Authentication). Use the local server there for now.

VS Code#

.vscode/mcp.json:

{
  "servers": {
    "taskcloud": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Authorization": "Bearer ${input:taskcloud-key}" }
    }
  },
  "inputs": [{ "id": "taskcloud-key", "type": "promptString", "description": "TaskCloud API key", "password": true }]
}

Codex and other clients#

Codex (~/.codex/config.toml) reads the key from an environment variable:

[mcp_servers.taskcloud]
url = "http://127.0.0.1:8787/mcp"
bearer_token_env_var = "TASKCLOUD_API_KEY"

Any other MCP client works if it supports either stdio (run npx -y @taskcloud/mcp with TASKCLOUD_API_KEY in its environment) or Streamable HTTP with a custom Authorization header.

Self-hosting the HTTP server#

npx -y @taskcloud/mcp --http --port 8787                       # listens on 127.0.0.1:8787, endpoint /mcp
npx -y @taskcloud/mcp --http --host 0.0.0.0 --read-only        # all interfaces, read-only tools

The server has no API key of its own. Each MCP request must send Authorization: Bearer <api key>, and the tools of that request call the API with that key only. TASKCLOUD_API_KEY in the server's environment is ignored in this mode, so two users of one server never share a key. The server only checks that the header is present. The API decides whether the key is valid, so a revoked key gets tool results with isError: true and 401 unauthorized.

Docker#

The image is built from the SDK sources (build context sdks/):

docker build -f sdks/mcp/Dockerfile -t taskcloud-mcp sdks
docker run --rm -p 8787:8787 taskcloud-mcp                     # add flags after the image name, e.g. --read-only

The container listens on 0.0.0.0:8787, runs as a non-root user and has a HEALTHCHECK on /healthz. Because it binds to all interfaces, the Host check is off unless you pass --allowed-hosts (or TASKCLOUD_MCP_ALLOWED_HOSTS) with the host name clients use. Put it behind a reverse proxy that terminates TLS, because API keys travel in a header.

Configuration#

Endpoints and behavior#

• POST /mcp: MCP messages (Streamable HTTP, protocol versions up to the current spec). The server is stateless: it issues no Mcp-Session-Id, every request is handled independently, and replicas behind a load balancer need no sticky sessions. Responses are plain JSON, not SSE streams.
• GET /mcp and DELETE /mcp return 405, because a stateless server has no server-initiated stream and no session to end. Clients handle this per the spec.
• GET /healthz: {"status":"ok", ...} for liveness and readiness probes.
• Per-request narrowing: /mcp?read_only=1 and /mcp?tools=exec,read_file shrink the tool list for that connection. They never widen what the server-wide --read-only or --tools allows.
• Timeouts: 15 s to receive headers, 30 s to receive the whole request, then the per-request deadline above.
• Logs: one JSON object per line on stderr, with request_id (taken from X-Request-Id or generated, and echoed in the response), status, duration, JSON-RPC methods, tool names and key_fp, the first 12 hex characters of the key's SHA-256. API keys, tool arguments and tool output are never logged.

Authentication#

Today the only credential is a TaskCloud API key in the Authorization header. MCP's OAuth 2.1 flow (protected resource metadata, browser sign-in, audience-bound tokens) is planned for the hosted endpoint. It needs an authorization server on the TaskCloud side, which does not exist yet. Until then, clients that only support OAuth for remote servers should use the local stdio server.

Tools#

Behavior notes:

• Truncated output. exec in sync mode returns exit_code, stdout and stderr. Output larger than what fits in a tool result is truncated, and the tool says where the full log can be read (GET .../commands/{command_id}/stream).
• Text files only. read_file and write_file handle text. For binary files, use the REST API or signed URLs.
• Wake on request. Tools that need a running VM wake a paused sandbox automatically.

Limiting what the agent can do#

The server accepts flags that remove tools from the list the agent sees:

npx -y @taskcloud/mcp --read-only                      # only list_sandboxes, get_sandbox, read_file, list_files, screenshot
npx -y @taskcloud/mcp --tools create_sandbox,exec,read_file,write_file,list_files,expose_port

For example, --tools without delete_sandbox stops the agent from deleting sandboxes. --read-only and --tools can be combined. API key scopes still apply.

The same flags work with --http. Over HTTP a client can also narrow its own tool list with ?read_only=1 or ?tools=a,b in the endpoint URL, for example https://mcp.task.cloud/mcp?tools=exec,read_file once the hosted endpoint is live.

Docs for agents#

• A concise index of this documentation for LLMs: https://task.cloud/docs/llms.txt
• The OpenAPI spec for generating clients: see API reference