# Use Clanker Workspace from your own agent

Canonical: https://clankercloud.ai/workspace-agents

Reviewed: 2026-10-17

Connect Claude, ChatGPT, OpenClaw, Hermes, or another compatible MCP agent to your Clanker Workspace with browser sign-in and permissions you control.

## Connect

Start with the [Workspace-hosted agent instructions](https://workspace.clankercloud.ai/for-agents.md).

1. [Create an account or sign in to Workspace](https://workspace.clankercloud.ai/agent-connect). Existing Cloud Portal accounts work here too.
2. Add the remote MCP URL to your agent: https://workspace.clankercloud.ai/mcp
3. Follow the agent’s browser sign-in prompt. Check the client name and callback address, then approve the permissions you want.
4. Ask the agent to list your projects and read a file. Start with a small task and inspect the saved result in Workspace.

## Permissions

- Read (workspace:read): projects, files, conversations, Agents, knowledge, job output, and available plans.
- Edit (workspace:write): files, conversations, and saved work.
- Configure and run (workspace:execute): projects, Agents, skills, workflows, schedules, session approval settings, hosted commands, and image generation when enabled. Commands can use files and the network and consume credits. Configuration changes can affect ongoing work.
- Plan checkout (workspace:billing): prepare a subscription checkout and check subscription status. Payment confirmation happens in Stripe. This permission requires read access and is independent of Edit and Configure and run.

Start with read access. Request workspace:write or workspace:execute only when the task needs them; execution also requires write access. Request workspace:billing only if the user wants plan checkout or subscription status, then explicitly select it on the Workspace consent screen. It starts unchecked. Existing connections never gain new permissions automatically.

Permissions apply across the connected account’s Workspace, including shared projects within the user’s existing role. The connection does not expose full account access, passwords, recovery codes, billing-portal access, subscription cancellation, or secret-management APIs. Hosted commands can access the files and network available to the Workspace machine.

## Client setup

### Claude

Open Customize → Connectors → Add custom connector and enter the Workspace MCP URL. Choose Sign in now and, when offered an OAuth client choice, Register automatically. Review permissions in Workspace and enable the connector for your conversation. Organization policies may control who can add connectors.

[Use Claude with Clanker Workspace](https://clankercloud.ai/learn/use-claude-with-clanker-workspace)

[Official Claude documentation](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)

### ChatGPT

Open ChatGPT Plugins → + → Add custom MCP server. Enter the Workspace MCP URL, configure OAuth, and complete browser authorization. Create the plugin and select it with @ in a new conversation. Account and organization policies apply.

[Use ChatGPT with Clanker Workspace](https://clankercloud.ai/learn/use-chatgpt-with-clanker-workspace)

[Official ChatGPT documentation](https://developers.openai.com/plugins/deploy/connect-chatgpt)

### OpenClaw

Start with read access. Save a Streamable HTTP server with OAuth enabled, then run the login command and approve access in Workspace.

```
openclaw mcp set clanker '{"url":"https://workspace.clankercloud.ai/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"workspace:read"}}'
openclaw mcp login clanker
```

Optional plan checkout: request read and billing access, log in again, and select the checkout permission. This configuration does not request edit or execution access.

```
openclaw mcp set clanker '{"url":"https://workspace.clankercloud.ai/mcp","transport":"streamable-http","auth":"oauth","oauth":{"scope":"workspace:read workspace:billing"}}'
openclaw mcp login clanker
```

[Official OpenClaw documentation](https://docs.openclaw.ai/cli/mcp/transports)

### Hermes

Add this server to your Hermes configuration, then run hermes mcp login clanker. Hermes opens the browser for authorization.

```
mcp_servers:
  clanker:
    url: "https://workspace.clankercloud.ai/mcp"
    auth: oauth
```

[Official Hermes documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)

Other clients need Streamable HTTP MCP, OAuth authorization code with S256 PKCE, resource indicators, and dynamic public-client registration. Client-version compatibility is separate from Clanker server deployment; check the client documentation and the tools returned by tools/list.

After a server update, refresh its tool metadata in your client and start a new conversation. The managed-task surface is server version 2.0.0; changing tools now require sessionId.

## Managed tasks you can watch and take over

Read-only discovery needs no task Session. Before any data change or execution, call workspace_start_session with name, provider (claude/chatgpt/codex/custom), agentName, the selected projectId (or general), initialMessage containing the user-authorized task, and a stable idempotencyKey (12–200 characters). Retain item.id as sessionId. Repeat identical inputs/key only to recover an uncertain start; an ended task cannot be restarted.

Pass sessionId to every changing tool. Call workspace_heartbeat_session with sessionId and concise public progress at least once a minute; the lease lasts fifteen minutes. Record progress and results with workspace_append_message. The external conversation is not copied automatically. Do not save secrets or private reasoning.

The user can open Sessions to watch. Take over stops the task, prevents later publication, requests cancellation of linked jobs/images, and disconnects this MCP connection. Stop when a task is inactive or access is revoked; reconnecting or starting replacement work requires fresh human authorization. Already submitted external effects cannot be recalled.

After reading back saved outputs, append a final assistant message and call workspace_complete_session with sessionId, status succeeded or failed, and the returned finalMessageId. Retain the original file/job/task IDs when reconciling uncertain results.

## Planner and Apps

Use workspace_list_todos and workspace_get_todo to read Planner tasks. workspace_create_todo requires title, idempotencyKey and sessionId. workspace_update_todo also requires todoId and the observed expectedRevision. A stale revision requires rereading; identical retries keep their action key. Creating a task does not execute it.

workspace_list_apps and workspace_get_app read Apps. workspace_create_app creates a draft with name, projectId, sessionId and a stable idempotencyKey; it requires execution permission and native account quotas. It does not build, deploy or publish. Use the separately authenticated HTTP API for supported build/publication actions only when explicitly authorized.

## Terminal and curl access

Read the [HTTP agent guide](https://workspace.clankercloud.ai/for-agents.md) and [API reference](https://workspace.clankercloud.ai/workspace-api.json). The browser-approved workspace-login.py helper works with Google/GitHub and password accounts. It creates a private terminal cookie login after the user compares a code and approves. Terminal account cookies, CSRF and MCP OAuth tokens are separate and cannot be interchanged.

## Purchase a plan

Use the same account created in Workspace or the Cloud Portal. Ask workspace_list_plans for the available plans; this requires workspace:read. To inspect the connected account’s subscription, request workspace:billing and call workspace_billing_status.

After the user chooses a plan, call workspace_prepare_plan_checkout with the returned plan identifier and a stable idempotencyKey. This requires workspace:billing and prepares an account-bound Stripe subscription checkout. Open the returned hosted Stripe checkout so the user can review the plan, enter payment details, and confirm the purchase. The agent must not request card details, passwords, or recovery codes in chat. Preparing a checkout does not itself purchase the plan.

After payment, call workspace_billing_status to check the subscription. A checkout URL or browser success redirect is not proof that the plan is active. If checkout preparation times out, retry with the same plan and idempotencyKey so the existing operation can be reconciled; do not create another purchase with a new key. This connection cannot open the billing portal or cancel a subscription.

## Image generation (when enabled)

Discover workspace_generate_image, workspace_get_image_generation, and workspace_cancel_image_generation. Generation and cancellation require execution permission. Start a managed Session in the destination Project; pass its sessionId, the destination projectId, a new PNG outputPath and a stable idempotencyKey. Poll the returned job before claiming delivery. Saved images stay in that Project. References must be exact image file IDs/revisions from that Project. Generation uses credits; cancelling a submitted request may still incur usage. Never regenerate an uncertain outcome automatically. Business/protected inference is unavailable in this initial integration.

## Work and recovery

Use workspace_list_items to find projects and sessions. Read files with workspace_read_file, following nextOffset until truncated is false. Writes require expectedRevision: 0 for a new file or the revision just read. workspace_write_file handles UTF-8 files up to 256 KiB; workspace_patch_files supports exact edits to files up to 64 KiB. Use hosted commands for larger or binary outputs when execution is approved.

workspace_run_command returns a durable job and requires a stable idempotencyKey. Inspect workspace_get_job and workspace_job_events after a timeout. Never repeat commands or writes with unknown effects. Saved session messages are records; appending a message does not start a Clanker model conversation. Use your connected agent’s intelligence to carry out the task with the exposed tools.

## Usage and credits

Clanker-hosted model tokens and Workspace compute are attributed to the user who authorizes the work. The external agent’s own model calls stay with its provider; Workspace cannot count those tokens. MCP reads and saved messages do not themselves invoke a Clanker model. Inspect account usage and retain operation keys when reconciling retries.

## Disconnect

[Manage connected agents](https://workspace.clankercloud.ai/agent-connect) in Workspace, or open Settings → External agents. Access expires after 30 days. Disconnecting blocks future requests; work already queued may continue and can be stopped separately. Access tokens last at most one hour, and refresh tokens rotate. Password changes and recovery revoke agent connections. Disconnecting does not cancel a previously prepared checkout link.

## Desktop and other APIs

This hosted connection works without installing Clanker Desktop. For local computer control, use the [desktop setup guide](https://clankercloud.ai/agent-onboarding). Sandbox API, project-scoped Team MCP, and Marketplace access remain separate interfaces.