Agents & clients

Workstate is not an agent, and it does not run agents. The agents you already use connect to it over MCP, the Model Context Protocol: an open standard for connecting AI tools to data. Through Workstate's tools, an agent searches what your team knows and records what it decides.

How an agent connects

Workstate has two MCP servers. Both use the Streamable HTTP transport.

Server name	Address	Tools
`rag-corpus`	`https://mcp-uat.workstate.io/corpus`	`search_corpus`, `reindex_corpus`
`rag-ledger`	`https://mcp-uat.workstate.io/ledger`	`ledger_search`, `ledger_get`, `ledger_create`, `ledger_append`, `ledger_move`, `ledger_archive`

Requests carry these headers:

Header	Required	What it does
`Authorization: Bearer <key>`	Yes	Your API key. The agent acts as the person who owns the key.
`X-RAG-Namespace: <namespace id>`	No	The namespace to use, such as `ws-…`. It must be one you have access to. Without it, the agent uses your oldest namespace.
`X-RAG-Agent: <label>`	No	A name for the agent, such as `codex`. Ledger entries carry it when the agent does not name itself in the tool call.

Everything an agent records is attributed to the person whose key it used, together with the agent's name. See Keys & attribution. MCP tools describes every tool.

Get your configuration

In the console, choose a namespace in the switcher at the top of the sidebar.
Open API keys. Under Create a key, describe where you will use the key, and select Create key. Copy the key and store it safely. See API keys.
In Connect your agent, select Copy.

The configuration connects an agent to the selected namespace. It reads the key from the RAG_API_KEY environment variable, so it holds no secret. For your oldest namespace, it looks like this:

json

{
  "mcpServers": {
    "rag-corpus": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/corpus",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-…"
      }
    },
    "rag-ledger": {
      "type": "http",
      "url": "https://mcp-uat.workstate.io/ledger",
      "headers": {
        "Authorization": "Bearer ${RAG_API_KEY}",
        "X-RAG-Namespace": "ws-…"
      }
    }
  }
}

For any other namespace, the server names end with its id, such as rag-corpus-ws-…. That keeps each namespace's servers apart, so you can switch namespace, copy again, and add the new pair to the same file. See Managing namespaces.

Claude Code reads this configuration as it is. Other clients use a different file or a slightly different syntax, shown on each client's page.

Server names

Clients name each tool after its server: in Claude Code, for example, the search tool is mcp__rag-corpus__search_corpus. Agent instructions refer to the tools by the server names rag-corpus and rag-ledger, and some clients load a tool only when it is asked for by its exact name. If the server names and the instructions disagree, the agent doesn't find the tools, and nothing tells you so.

An agent that uses one namespace: name its servers rag-corpus and rag-ledger. The console already does this for your oldest namespace. For any other, it adds the namespace id to the names, so rename them. The X-RAG-Namespace header, not the server name, decides the namespace.
An agent that uses several namespaces at once: give each namespace's servers their own names, such as the ones the console gives, and say in the agent's instructions which names cover which namespace. See Connect an agent to several namespaces.

Choose your client

Client	Where the configuration goes	How it gets the key
Claude Code	`.mcp.json` in your project, or your user configuration	`${RAG_API_KEY}`, or a script that reads the key from the macOS Keychain
Claude desktop	`.mcp.json` in your project, for the Code tab. Chat cannot connect yet.	On macOS, a script that reads the key from the Keychain. On Windows, `${RAG_API_KEY}`.
Cursor	`.cursor/mcp.json` in your project, or `~/.cursor/mcp.json`	`${env:RAG_API_KEY}`
Codex	`~/.codex/config.toml`	`bearer_token_env_var = "RAG_API_KEY"`
Other MCP clients	The client's MCP settings. VS Code is shown as an example.	Depends on the client
Your own agent	Your code, through an MCP client library or the REST API	The `Authorization` header

Claude CodeUse the generated configuration as it is, with your key in an environment variable or the macOS Keychain.Claude desktopThe Code tab works today. Chat needs MCP OAuth, which is coming.CursorAdd both servers to mcp.json, reading the key from your environment.CodexAdd both servers to config.toml with a bearer token variable.Other MCP clientsAnything that speaks MCP over Streamable HTTP and can send headers.Your own agentCall the MCP servers from your code, or search through the REST API.

Teach the agent to use Workstate

Connecting gives an agent the tools. Instructions make it use them well: search before it acts, cite what it found, and record what it decided. Agent instructions has text you can paste.

Keep your key safe

Never put the key in a file that might be committed. The configurations in these guides hold only a reference to the key, such as ${RAG_API_KEY}.
Make one key for each machine or agent, so that you can revoke one without stopping the others.
Do not share a key. Everything done with it is recorded as its owner's.

Agents & clients ​

How an agent connects ​

Get your configuration ​

Server names ​

Choose your client ​

Teach the agent to use Workstate ​

Keep your key safe ​

Related ​