Workspaces

Every read is scoped to one workspace. This is the setting that makes results look empty.

An agency keeps each client in its own workspace. Every read is scoped to exactly one of them, and with no workspace named you read the account’s home workspace.

On an agency account the home workspace is often not where the live businesses are. If a list comes back empty or surprisingly small, that is the first thing to check, not evidence that the account has no data.

Find the right one

List the workspaces, then pass the id you want.

MCP

Call list_workspaces, then pass workspace_id to any other tool.

Over MCP the workspace_id parameter accepts the id, the name or the slug. Over HTTP, send the X-Workspace-Id header.

Ids do not cross workspaces

A business id read in one workspace does not resolve in another. Passing it anyway returns an empty result rather than an error, which reads exactly like “this client has no reviews”. Always pass ids you read in the same workspace you are querying.

A refused workspace is refused loudly

If you name a workspace the credential cannot read, the request fails with 403. It is never quietly answered from the default workspace instead. That is deliberate: silently substituting a different tenant’s rows under the name you asked for is the worst possible answer, because nothing in the response says it happened.

Two cases produce it: the workspace belongs to another agency, or the account is a client user pinned to a single workspace.

Pinning a whole connection

Clients that can only send static headers can pin one workspace for the life of the connection:

claude mcp add --transport http reputably https://app.reputably.net/api/mcp \
  --header "Authorization: Bearer rpk_your_key_here" \
  --header "X-Workspace-Id: ws_abc123"

A per-call workspace_id still overrides it, so one conversation can span several workspaces.

Platform access

A credential with platform scope reads every agency’s workspaces, and list_workspaces then reports business counts per workspace plus a total across all of them. Use that total for account-wide counts rather than paging each workspace.

Outside its own agency that credential is read-only: drafts, reports, tracking setup and marking leads seen are all refused, while staying available inside its own agency.