Pattern: one namespace per client

Keep each client's or project's knowledge and decisions apart.

Who it's for

Agencies, consultancies and managed service providers with several clients. Also companies with products or business units whose material must stay separate.

How it works

A namespace is a separate index in your account. Each one has its own sources, its own search results and its own ledger. A request for a namespace you have no access to is refused, with no grant for namespace. Topic ids are unique only within a namespace.

One namespace per client keeps each client's code, documents and decisions away from every other client's.

Set it up

1. Create a namespace for each client. An admin opens Namespaces, enters a name such as "Client A" and selects Create. The console shows the namespace's id, which starts with ws-. That id is what an agent sends.
2. Add the client's sources inside it. Select the namespace in the switcher at the top of the console's sidebar, open Sources and choose a source under Add a source. A source belongs to the namespace it was created in.
3. Pin each project folder to one namespace. With the client's namespace selected in the switcher, open API keys and copy the configuration under Connect your agent. It holds only that namespace's pair of servers. Save it as .mcp.json in the client's project folder. Unless the namespace is your oldest, the server names end in its id. Rename them to rag-corpus and rag-ledger, because agent instructions refer to the tools by those names. The result looks like this:

{
  "mcpServers": {
    "rag-corpus": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/corpus",
      "headers": { "Authorization": "Bearer ${RAG_API_KEY}", "X-RAG-Namespace": "ws-<client A's namespace id>" }
    },
    "rag-ledger": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/ledger",
      "headers": { "Authorization": "Bearer ${RAG_API_KEY}", "X-RAG-Namespace": "ws-<client A's namespace id>" }
    }
  }
}

An agent working in client A's folder then searches and records only in client A's namespace.

Keys reach every namespace you hold

A key has no scopes. One key reaches every namespace its person has access to, and the X-RAG-Namespace header picks one for each request. Workstate checks the header against your access on every call.

• Always set the header. With no header, Workstate uses the oldest namespace you have access to, which may belong to another client.
• Connect your agent shows the pair of servers for the namespace selected in the switcher. For your oldest namespace, they're named rag-corpus and rag-ledger. For any other, the names end in a hyphen and the namespace id. In a client's folder, use the unsuffixed names with that client's id, as above. To connect one agent to several namespaces, see Managing namespaces.
• Pinning a folder prevents mistakes, but it isn't a security boundary. The same key can still reach your other namespaces.

Who can reach each namespace

Everyone who is an owner or admin when a namespace is created is given it. Anyone else reaches a client's namespace only when an owner or admin gives it to them:

• When inviting. In the Invite a teammate dialog, under Namespaces, select the namespaces of the clients the person works for.
• Later. On the Team page, open the picker in the person's row, under Namespaces. Select a namespace to give it to them, or select a ticked one to take it away. Each change applies from the person's next request.

You can give only the namespaces you hold. Nobody can change their own access, and only an owner can change an owner's.

Owners and admins are given every new namespace, so by default they reach every client's. Invite people who work for only some clients as Members, with only those clients' namespaces.

Record decisions per client

• Each client's ledger lives in that client's namespace. File topics under projects that make sense to the client, such as a repository or workstream name.
• ledger_move refiles a topic under another project in the same namespace. It doesn't move topics between namespaces, so record each one in the right namespace from the start.

When an engagement ends

When someone stops working for a client, take that client's namespace away from them in the Namespaces column on Team. Their keys keep working in the namespaces they still hold.

When the whole engagement ends, you can delete the client's namespace. Deleting a namespace removes its sources, everything indexed from them, and its ledger topics. It can't be undone. The console asks you to type the namespace's name to confirm, and the id is never used again. There's no bulk export, so agree with the client what they need before you delete. On some deployments, deleting a namespace may be unavailable.

Limits to know

• Keys have no scopes. Anyone with access to two clients' namespaces reaches both with one key.
• Everyone with access to a namespace sees everything in it.
• A person can hold seats in more than one Workstate account, for example when a client runs its own account and invites you. Switching accounts in the console Coming soon isn't available yet.

Next steps

• Managing namespaces
• Namespaces
• API keys