> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clustr-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Working in a workspace

> Use the API and MCP tools inside one of your workspaces

`/api/org/v1` holds the calls for your organization as a whole (see the
[Organization API](https://docs.clustr-ai.com/enterprise/api-reference/introduction.md)). Everything you do inside one
client's workspace, such as importing, reading jobs and paths, tags and saved views, is in the
[API Reference](https://docs.clustr-ai.com/api-reference/introduction.md). Call those endpoints with your organization key
and name the workspace.

## In the API

Add the `X-Clustr-Tenant` header to any `/api/public/*` call. Its value is the workspace's
`id` or your own `externalId`.

```bash theme={null}
curl "https://api.clustr-ai.com/api/public/jobs?status=PROCESSING" \
  -H "Authorization: Bearer $CLUSTR_ORG_KEY" \
  -H "X-Clustr-Tenant: client-1234"
```

Rules:

* The header is required. A request without it answers `400`.
* The workspace must be one of yours. Any other id answers `404`.
* Reads (`GET`) need the `data:read` scope. Every other method needs `jobs:write`.
* A suspended workspace refuses writes and still answers reads.
* Writes are recorded in `GET /api/org/v1/audit-log`.
* `Idempotency-Key` on an import means a retry cannot start the job twice. See
  [Bulk jobs](https://docs.clustr-ai.com/enterprise/bulk-jobs.md#retry-safely).

## In MCP, with a key

The [MCP server](https://docs.clustr-ai.com/mcp-server.md) accepts the same header. Set it on the connection:

```json theme={null}
{
  "mcpServers": {
    "clustr-client-1234": {
      "url": "https://api.clustr-ai.com/mcp",
      "headers": {
        "Authorization": "Bearer clo_...",
        "X-Clustr-Tenant": "client-1234"
      }
    }
  }
}
```

Every tool then reads and writes that workspace. Add one connection for each workspace you
want side by side.

## In MCP, signed in

If you are an organization admin and signed in to MCP as a person, use the
`org_switch_tenant` tool. It makes every other tool act inside another workspace of your
organization.

```text theme={null}
org_switch_tenant  tenant: "client-1234"
```

* `tenant` is the workspace `id` or your `external_id`.
* `tenant: "home"` switches back to your own workspace.
* It lasts one hour, in that MCP session only. It stops working if you stop being an
  organization admin.
* An API key cannot use this tool. A key uses the header above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.