Claude Code

Claude Code connects to Workstate's two MCP servers over HTTP. The configuration that the console generates is written for Claude Code, so you can use it as it is. What you choose is how Claude Code gets your API key.

What you need

• A Workstate API key. See API keys.
• The configuration from Connect your agent, on the console's API keys page. See Agents & clients.
• Claude Code, in a terminal or in the Code tab of the Claude desktop app.

Choose how Claude Code gets your key

Method	Works in	Choose it when
An environment variable	Claude Code started from a terminal where the variable is set, and the desktop app on Windows	You work in a terminal, on any operating system, or in the desktop app on Windows
The macOS Keychain	The terminal and the desktop app, on macOS	You use the desktop app on macOS, or you want the key kept out of your environment

Option 1: an environment variable

1. In your terminal, set the key as RAG_API_KEY:

   export RAG_API_KEY='rgc_live_…'

   To keep the key out of your shell history, run read -rs RAG_API_KEY && export RAG_API_KEY instead, paste the key and press Return. To set the key in every new terminal, add the export line to your shell profile, such as ~/.zshrc, but only if that file is not kept in a Git repository.

2. Save the configuration from Connect your agent as .mcp.json in your project's root folder. The file holds no secret, so you can commit it and share it with your team. Each person sets their own RAG_API_KEY.

3. In that folder, start Claude Code from the same terminal:

   claude

4. When Claude Code asks whether to use the project's MCP servers, approve rag-corpus and rag-ledger.

Claude Code fills in ${RAG_API_KEY} from its environment when it starts. To reach Workstate from every project on a Mac, not only this one, use option 2, which also works in your user configuration.

Option 2: the macOS Keychain

Claude Code can run a small script, called a headersHelper, that prints the request headers each time it connects. With this method, the key lives only in your Keychain.

1. Add the key to your Keychain. The command asks for the key, so it stays out of your shell history:

   security add-generic-password -U -a "$USER" -s workstate-api-key -w

2. Save this script as ~/.config/workstate/mcp-headers.sh:

   #!/bin/sh
   key=$(security find-generic-password -a "$USER" -s workstate-api-key -w 2>/dev/null) || {
     echo "No Keychain item named workstate-api-key" >&2
     exit 1
   }
   printf '{"Authorization": "Bearer %s"}\n' "$key"

3. Make the script executable:

   chmod +x ~/.config/workstate/mcp-headers.sh

4. Point Claude Code at the script instead of the Authorization header. Keep the X-RAG-Namespace header. In the examples, replace /Users/you with your home folder and ws-… with your namespace id.

   For one project, use this as the project's .mcp.json:

   {
     "mcpServers": {
       "rag-corpus": {
         "type": "http",
         "url": "https://mcp-uat.workstate.io/corpus",
         "headers": { "X-RAG-Namespace": "ws-…" },
         "headersHelper": "/Users/you/.config/workstate/mcp-headers.sh"
       },
       "rag-ledger": {
         "type": "http",
         "url": "https://mcp-uat.workstate.io/ledger",
         "headers": { "X-RAG-Namespace": "ws-…" },
         "headersHelper": "/Users/you/.config/workstate/mcp-headers.sh"
       }
     }
   }

   For every project you open in a terminal, add both servers to your user configuration instead. For the desktop app, use the project's .mcp.json, as above.

   claude mcp add-json rag-corpus '{"type":"http","url":"https://mcp-uat.workstate.io/corpus","headers":{"X-RAG-Namespace":"ws-…"},"headersHelper":"/Users/you/.config/workstate/mcp-headers.sh"}' --scope user
   claude mcp add-json rag-ledger '{"type":"http","url":"https://mcp-uat.workstate.io/ledger","headers":{"X-RAG-Namespace":"ws-…"},"headersHelper":"/Users/you/.config/workstate/mcp-headers.sh"}' --scope user

Claude Code runs the script in a shell and sends the headers it prints. The script must print one JSON object and finish within 10 seconds. For a server in a project's .mcp.json, Claude Code runs the script only after you trust the project folder, and without environment variables whose names look like credentials, such as RAG_API_KEY. That is why the script reads the Keychain rather than an environment variable.

In the Claude desktop app

The Code tab of the Claude desktop app runs Claude Code. For the desktop app, put Workstate's servers in the project's .mcp.json. How you supply the key depends on your operating system:

• On macOS, use option 2.
• On Windows, the app inherits your user environment variables. Set RAG_API_KEY as a user environment variable, restart the app, and use the configuration from option 1.

On macOS, the desktop app does not see RAG_API_KEY from your shell profile

When you open the desktop app from the Dock or Finder, it takes only PATH and a fixed set of Claude Code's own variables from your shell profile. It does not see a RAG_API_KEY that you export there, so every call fails with 401.

Check it worked

1. In a terminal, in your project folder, run:

   claude mcp list

   Both rag-corpus and rag-ledger show ✔ Connected. Inside Claude Code, the /mcp command shows the same.

2. Ask a question that your sources can answer, and ask for citations. For example:

   Use search_corpus to find where we validate webhook signatures.
   Cite the repository, file and lines for each result.

3. On API keys, the key's Last used time updates.

Give Claude Code the instructions

Paste the text from Agent instructions into CLAUDE.md in your project's root folder, for everyone who works on the project. For all your projects, paste it into ~/.claude/CLAUDE.md.

Troubleshooting

What you see	Likely cause	What to do
claude mcp list warns that a variable is missing	RAG_API_KEY is not set where Claude Code started, so Claude Code sends ${RAG_API_KEY} as it is, and every call fails with 401.	Set the variable in that terminal and start Claude Code again. In the desktop app on macOS, use option 2.
Calls fail with 401: missing bearer token or invalid or revoked key	The key is empty where Claude Code runs, or it was revoked, or it was copied with a character missing or added.	Check that RAG_API_KEY or the Keychain item holds the whole key. If the key was revoked or lost, create a new one.
⏸ Pending approval	You have not approved the project's servers.	Run claude in the project folder and approve them.
✘ Failed to connect, with option 2	The script is missing, not executable, or cannot find the Keychain item.	Run ~/.config/workstate/mcp-headers.sh > /dev/null && echo ok. It prints ok when the script can read the key. Otherwise, repeat the steps of option 2.
no grant for namespace "ws-…"	The X-RAG-Namespace header names a namespace you do not have access to.	Copy the configuration again from API keys, with the right namespace selected.
principal has no workspace grants	You have not been given a namespace yet.	Ask an owner or admin to give you one on the Team page. See Team & invites.
Searches return nothing, or not what you expect	The first sync has not finished, or your sources are in another namespace.	Check that the sources show Up to date, and that the namespace id in your configuration is the one your sources are in.
repo not given and could not be inferred from a git repo	The agent tried to record a ledger topic without naming a project.	Tell it which project to file the topic under.
The tools do not appear	.mcp.json is not in the folder where Claude Code started, or the servers are not approved.	Start Claude Code in the project's root folder, and approve the servers.

Related

• Agents & clients
• Agent instructions
• API keys
• MCP tools