Many clients, one MCP server: the account keyring

An agency doesn't have one client. It has ten, and each one has its own CognitionDesk account.

With a single key, serving two clients from the same agent means running the MCP server twice, with two .env files. That's two copies of every tool in each session, both answering fine, and neither telling you which account you're in. Reading the right answer from the wrong account doesn't throw an error. It just looks like the right answer.

Since 0.9.0 (the first npm release that ships it), @cognitiondesk/mcp has a keyring: one instance, several accounts.

1. Accounts, with aliases

claude mcp add cognitiondesk \
  -e 'COGNITIONDESK_ACCOUNTS={"client-a":"<key for A>","client-b":"<key for B>"}' \
  -- npx -y @cognitiondesk/mcp

It's a JSON object, {"alias": "<key>"}. The first account is active at startup (or whichever COGNITIONDESK_ACTIVE_ACCOUNT names). If an account lives on a different backend, write it as an object: {"key": "…", "url": "https://…"}. COGNITIONDESK_API_KEY on its own still works as before: it's a one-account keyring named default.

No tool ever returns a key's value. The only thing that leaves the keyring is the aliases.

2. Switching accounts is a tool

This is real output from 0.10.0 with two test keys:

> use_account {"name":"client-b"}
account: client-b

Active account is now 'client-b'. Available: client-a, client-b.

get_connection_status lists the keyring's accounts and which one is active. Read tools also take an account argument to look at another account without switching, for example to compare A's assistant with B's.

3. Every response says which account it came from

Every response, errors included, starts with account: <alias>. That line isn't decoration: if your agent is about to edit an assistant and the line says client-a when you thought you were in B, you see it before the write.

The rule worth giving your agent is short: writes always go to the active account. Call use_account first, then edit, and check the line that comes back.

What the keyring doesn't do

The remote MCP (mcp.cognitiondesk.com/mcp) doesn't use the keyring. There, every request carries its own key in x-api-key, and the server never falls back to a key from its environment. If it did, one remote client could end up working on someone else's account. The keyring is for the MCP that runs on your machine through npx.

It's in the MCP guide. If you run more accounts than fit comfortably in one keyring, write to us.