# Use Clanker Workspace from your own agent

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

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, and hosted commands. 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

Add a custom connector in Claude, enter the Workspace MCP URL, then connect and approve access in your browser. Organization policies may control who can add connectors.

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

### ChatGPT

Where developer mode is available, add the Workspace MCP URL as a custom connection, then complete browser authorization. Availability depends on your account and organization policy.

[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.

## 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.

## 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.