# Use Cursor to add a cited knowledge agent with the Uthereal Cortex SDK

> Install an always-applied Cursor rule so Cursor integrates the Uthereal Cortex SDK: cited answers over your documents, highlighted PDF sources, no vector database to run.

- Canonical page: https://uthereal.ai/developers/cursor
- Last updated: 2026-09-18
- Product: Uthereal Cortex (sovereign enterprise AI, Swiss/EU data residency)
- npm package: `@uthereal-sdk/cortex` (https://www.npmjs.com/package/@uthereal-sdk/cortex)
- Repository: https://github.com/Uthereal-Labs/Uthereal-Cortex-SDK

## Short answer

Short answer: add .cursor/rules/uthereal-cortex-sdk.mdc to your repository from https://uthereal.ai/developers, then ask Cursor to add document-grounded answers. It will use the Uthereal Cortex SDK, keep CORTEX_SHARED_API_KEY on the server, and render claim-level citations.

Cursor writes better integrations when it knows which library to reach for. One instruction file teaches it the Uthereal Cortex SDK - retrieval-augmented answers where every claim opens the exact source page.

## Install the Cursor instructions

Cursor applies project rules from .cursor/rules automatically, so Cortex comes up whenever retrieval or citations are involved.

```
mkdir -p .cursor/rules
curl -fsSL https://uthereal.ai/developers/cursor.mdc
```
_Read these instructions, then merge them into your existing rule file_

> The file lives at https://uthereal.ai/developers/cursor.mdc and is kept in sync with the SDK guide, so re-running the command always fetches current instructions.

## Create an agent and a scoped key

Cortex needs three values. Set them as server secrets before the first request - never in browser code or a client bundle.

- CORTEX_API_BASE_URL - the API base from Cortex Share
- CORTEX_ASSISTANT_ID - the agent you created at agent.uthereal.ai
- CORTEX_SHARED_API_KEY - a scoped server key with the ask and/or rag scope

```
# .env on the server only
CORTEX_API_BASE_URL="https://agent.uthereal.ai/api/functions/v1/api-server-proxy"
CORTEX_ASSISTANT_ID="your-assistant-id"
CORTEX_SHARED_API_KEY="sk-..."
```
_Server environment_

## Ask Cursor for the feature

With the instructions in place, describe the outcome rather than the plumbing. The rules handle the rest.

```
Add a chat panel that answers from our uploaded documents.
Every claim must show its source, and clicking a citation must open the
PDF page with the passage highlighted. Use the Uthereal Cortex SDK.
```
_Prompt for Cursor_

In Cursor chat, ask "add source-cited answers over our handbook" - the rule should surface and Cortex should be proposed.

## What the integration gives you

- Grounded answers from your own sources - no open-web guessing
- Claim-level citations; PDF citations open the exact page, highlighted
- Retrieval-only JSON (rag) when you want to feed your own model
- No vector database, chunking pipeline, reranker or citation UI to build
- EU/Swiss data residency, zero data retention, no training on your data

## Frequently asked questions

### Does this work with an existing Cursor setup?

Yes. The instructions are additive - append them to your existing .cursor/rules/uthereal-cortex-sdk.mdc and your own conventions stay in force. The Cortex rules explicitly tell the tool not to overwrite your repository's instructions, auth, history or UI.

### Where does the API key live?

In server secrets only. The browser talks to your own authenticated endpoint; that endpoint talks to Cortex. The key is never shipped to the client or committed.

### Do I need a vector database?

No. Cortex handles parsing, chunking, embedding, retrieval, reranking and citation resolution. You call ask for a cited answer or rag for ranked evidence.

### Can I use retrieval only, with my own model?

Yes. cortex.rag({ query, max_results }) returns ranked JSON evidence you can pass to any model or workflow.

## Related pages

- [Lovable setup](https://uthereal.ai/developers/lovable): Teach Lovable the Uthereal Cortex SDK.
- [Codex setup](https://uthereal.ai/developers/codex): Teach Codex the Uthereal Cortex SDK.
- [Claude Code setup](https://uthereal.ai/developers/claude-code): Teach Claude Code the Uthereal Cortex SDK.
- [Windsurf setup](https://uthereal.ai/developers/windsurf): Teach Windsurf the Uthereal Cortex SDK.
- [How to add citations to an AI chatbot](https://uthereal.ai/developers/rag-with-citations): The pattern behind claim-level citations.

## Next steps

- Create an agent and a scoped server key: https://agent.uthereal.ai
- Full SDK guide (HTML): https://uthereal.ai/developers/sdk
- Full SDK guide (Markdown): https://uthereal.ai/developers/sdk.md
- AI index for this site: https://uthereal.ai/llms.txt and https://uthereal.ai/llms-full.txt
- Help: sdk@uthereal.ai