Other MCP clients

Any MCP client can connect to Workstate if it can do two things: use the Streamable HTTP transport, and send request headers. This page lists what such a client needs, and shows VS Code as an example.

What any client needs

Setting	Value
Transport	Streamable HTTP
Search server	Name rag-corpus, address https://mcp-uat.workstate.io/corpus
Ledger server	Name rag-ledger, address https://mcp-uat.workstate.io/ledger
Authorization header	Bearer followed by your API key
X-RAG-Namespace header	Your namespace id, such as ws-…. Optional: without it, the client reaches your oldest namespace.
X-RAG-Agent header	A name for the client, such as vscode. Optional: ledger entries carry it when the agent does not name itself.

Name the servers rag-corpus and rag-ledger. Agent instructions refer to the tools by these names. See Server names.

Read the key from wherever your client keeps secrets, such as an environment variable or a password prompt. Never write the key itself into a configuration file that might be committed.

The servers are stateless: each request stands on its own, so an idle client does not need to reconnect. A client that supports only local servers, which it starts as programs on your computer, cannot connect to Workstate. Nor can a client that cannot send request headers.

Example: VS Code

In VS Code, MCP servers serve the chat's agent mode. VS Code can ask for your key once and store it securely, so the key is never in a file.

1. Create .vscode/mcp.json in your project's folder. Replace ws-… with your namespace id:

   {
     "inputs": [
       {
         "type": "promptString",
         "id": "workstate-api-key",
         "description": "Workstate API key",
         "password": true
       }
     ],
     "servers": {
       "rag-corpus": {
         "type": "http",
         "url": "https://mcp-uat.workstate.io/corpus",
         "headers": {
           "Authorization": "Bearer ${input:workstate-api-key}",
           "X-RAG-Namespace": "ws-…"
         }
       },
       "rag-ledger": {
         "type": "http",
         "url": "https://mcp-uat.workstate.io/ledger",
         "headers": {
           "Authorization": "Bearer ${input:workstate-api-key}",
           "X-RAG-Namespace": "ws-…"
         }
       }
     }
   }

   VS Code uses servers where other clients use mcpServers.

2. Start the servers. The first time, VS Code asks for the Workstate API key. Paste it.

3. Run the command MCP: List Servers to check that both servers are running.

Check it worked

1. The client lists eight tools: search_corpus and reindex_corpus from rag-corpus, and ledger_search, ledger_get, ledger_create, ledger_append, ledger_move and ledger_archive from rag-ledger.
2. Ask a question that your sources can answer, and ask for citations.
3. On API keys, the key's Last used time updates.

Troubleshooting

What you see	Likely cause	What to do
HTTP 401 with missing bearer token or invalid or revoked key	The key is not reaching Workstate, or it was revoked or copied incompletely.	Check how your client fills in the Authorization header. If the key was revoked or lost, create a new one.
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.
The tools are listed, but searches return nothing	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.
The client cannot add a server with custom headers	Some clients connect to remote servers only through OAuth.	Use another client. MCP OAuth for Workstate is on the way Coming soon.

Related

• Agents & clients
• MCP tools
• Your own agent
• Agent instructions