Cursor

Cursor connects to Workstate's two MCP servers over HTTP. Its configuration is close to the one the console generates, with two differences: Cursor reads an environment variable as ${env:NAME}, and it does not need the type field.

What you need

A Workstate API key. See API keys.
Your namespace id, such as ws-…. It is in the configuration under Connect your agent on the console's API keys page, and on the Namespaces page.
Cursor.

Connect Cursor

Set your key as the RAG_API_KEY environment variable, for example in your shell profile, such as ~/.zshrc:
bash
```
export RAG_API_KEY='rgc_live_…'
```
Keep the key out of any file that is kept in a Git repository. Then quit Cursor and open it again, so that it starts with the variable set.
Create the configuration file:
- For one project: .cursor/mcp.json in the project's root folder. It holds no secret, so you can commit it.
- For every project: ~/.cursor/mcp.json in your home folder.

Add both servers. Replace ws-… with your namespace id:

json

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

If you paste the configuration from the console instead, change each ${RAG_API_KEY} to ${env:RAG_API_KEY}. Name the servers rag-corpus and rag-ledger: if their names end in the namespace id, rename them. See Server names.

In Cursor, check that both servers are turned on. Cursor lists MCP servers under Customize in the sidebar.

Check it worked

Open the agent chat and check that Workstate's tools, such as search_corpus and ledger_search, appear under Available Tools.

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

text

Use search_corpus to find how we paginate API responses.
Cite the repository, file and lines for each result.

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

Give Cursor the instructions

Cursor reads AGENTS.md in your project's root folder, and project rules in .cursor/rules as .mdc files. Paste the text from Agent instructions into AGENTS.md, or into a rule that is always applied:

---
alwaysApply: true
---

(paste the agent instructions here)

Troubleshooting

What you see	Likely cause	What to do
Calls fail with 401: `missing bearer token` or `invalid or revoked key`	Cursor started without `RAG_API_KEY`, or the key was revoked or copied incompletely.	Quit Cursor and start it from a terminal where `RAG_API_KEY` is set. If the key was revoked or lost, create a new one.
Calls fail with 401 although `RAG_API_KEY` is set	The file uses `${RAG_API_KEY}`, which is not Cursor's syntax for an environment variable. Cursor's is `${env:RAG_API_KEY}`.	Correct the file, then turn the servers off and on again.
`no grant for namespace "ws-…"`	The `X-RAG-Namespace` header names a namespace you do not have access to.	Use a namespace id from the Namespaces page.
`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.
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 matches the namespace 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.

Cursor ​

What you need ​

Connect Cursor ​

Check it worked ​

Give Cursor the instructions ​

Troubleshooting ​

Related ​