MCP

Acting on behalf of a clientspace (delegation)

This guide explains the reserved clientspaceId argument, accepted by every verb tool (read, create, update, delete, act). You only need it in one specific situation: when you want to operate as one of your clientspaces (whitelabel sub-organizations) instead of your own organization. For all normal calls, leave clientspaceId out of arguments.

What a clientspace is

A clientspace is a whitelabel sub-organization under your (agency) account. Each clientspace has its own fully isolated data — campaigns, prospects, lists, senders — and its own API key. Agencies use clientspaces to run separate, branded workspaces per client.

Clientspace API keys are managed server-side and are never returned by any operation. You never see, store, or pass a clientspace's key. Instead you reference a clientspace by its integer clientspaceId, and the server supplies the right key for you.

The flow

1. Discover your clientspaces

List the clientspaces under your organization:

read(name: "clientspace/get", intent: { ... })

The response is a page of clientspaces, each with its clientspaceId, title, credit settings, etc. The apiKey field is intentionally absent — it is redacted. Pick the clientspaceId you want to act on behalf of. (You can also fetch a single one with clientspace/get_by_id.)

2. Run any operation on behalf of that clientspace

Call the operation exactly as you normally would, and add clientspaceId to its arguments, alongside the operation's normal arguments. For example, to list that clientspace's campaigns:

read(
  name: "campaign/get",
  arguments: { "pageQuery.limit": 10, clientspaceId: 12345 },
  intent: { ... }
)

The server looks up clientspace 12345, authenticates the request with that clientspace's API key, and returns its data. The same clientspaceId argument works on any operation (campaigns, prospects, lists, senders, messages, …) — it is accepted everywhere, even though it appears in no operation's Arguments table — and simply changes which organization the call acts as.

3. Go back to acting as yourself

Omit clientspaceId. The call uses your own organization's key, exactly as before. There is no persistent "switch" — delegation is per call.

Notes & errors

  • clientspaceId is a single positive integer inside arguments — the clientspaceId of one clientspace. It scopes the call and is never forwarded to the operation itself.
  • You never handle the clientspace's API key; the server resolves and caches it.
  • A non-integer or non-positive value → delegation_invalid, before the operation runs.
  • A clientspaceId that does not exist or is not under your organization → clientspace_not_found, before the operation runs. Re-check the id via clientspace/get.
  • If the clientspace exists but has no usable key, you get clientspace_key_unavailable.
  • Without clientspaceId, behavior is unchanged from a normal call.
  • To act as a workspace instead, use workspaceId (see workspace-delegation). clientspaceId and workspaceId are mutually exclusive — setting both is rejected with delegation_conflict before the operation runs.
  • Creating clientspaces (clientspace/post) requires a Clientspace/whitelabel plan; without it the call fails with 403 PLAN_REQUIRED and an upgrade URL (required-field validation runs first — a missing title is rejected with 400 MCP_VALIDATION_FAILED before the plan gate is even reached; do not re-authenticate).