Cursor

Telem adds web search, page reading and monitors to Cursor’s agent. The tools come from Telem’s hosted MCP server. A Telem hook sends your options with each search, keeps the searches of each chat together in the console, and records why the agent searched.

Before you begin

• Cursor. Telem is tested on Cursor 3.27, on the free plan, with the agent running on your computer.
• Node.js 20 or later, on the PATH that Cursor runs with. The installer runs on it, and so does the hook.

Create a Telem API key

1. Open your project
2. API keys
3. Issue API key

tlm_••••••••••••••••Keys start with tlm_.

Open the console

Never paste a key into a chat with Cursor. Every path below sets it for you.

Install

Connect Cursor to Telem

Installer

1. Run the installer in your terminal and pick Cursor. Paste your key when the installer asks. The field is masked, and the key never appears on screen.

   curl -fsSL https://docs.telem.ai/install.sh | sh

2. Restart Cursor. Cursor reads its MCP servers and hooks when it starts.

3. Ask Cursor’s agent to search the web. The search shows in the console.

Install with no prompts, for example in CI

curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client cursor --key-env TELEM_API_KEY

By hand

1. Add the server with your key. Put this in ~/.cursor/mcp.json, with your key in place of tlm_your_key. If the file already has mcpServers, add the telem entry to it.

   ~/.cursor/mcp.json

   {
     "mcpServers": {
       "telem": {
         "url": "https://mcp.telem.ai/mcp",
         "headers": { "Authorization": "Bearer tlm_your_key" }
       }
     }
   }

2. Restart Cursor. Cursor reads its MCP servers when it starts.

3. Ask Cursor’s agent to search the web. The search shows in the console.

This gives Cursor the tools, but not the hook: your .telem/telem.json options and the model’s reasoning are not sent, and the console does not keep a chat’s searches together. The installer adds the hook and the Telem skill.

Ask your agent

1. Start Cursor from a terminal with your key set, and paste this prompt in the agent chat. The agent runs the installer, which reads the key from TELEM_API_KEY, so the key never goes into the chat. If you have no cursor command, use the Installer tab.

   export TELEM_API_KEY=tlm_your_key
   cursor .

   Set up Telem web search for this coding agent.
   
   1. Read https://docs.telem.ai/llms.txt to learn what Telem is.
   2. Check that the TELEM_API_KEY environment variable is set. Do not print its
      value. If it is not set, stop and ask me to set it and restart you.
   3. Run the Telem installer for this agent, with no prompts:
      curl -fsSL https://docs.telem.ai/install.sh | sh -s -- --yes --client cursor --key-env TELEM_API_KEY
   4. Show me the installer's summary. Then tell me to restart Cursor,
      so that the Telem tools load.

2. Restart Cursor. Cursor reads its MCP servers and hooks when it starts.

3. Ask Cursor’s agent to search the web. The search shows in the console.

If it does not work, see If something goes wrong.

Tools

Search and read

4 tools

• telem_search Searches the web on several providers in one call.
• telem_fetch Reads the full text of up to 5 pages.
• telem_providers Lists the search providers.
• telem_session_history Lists the earlier searches in a session.

Monitors

4 tools

• create_monitor Runs a search on a schedule and keeps only new results.
• list_monitors Lists your monitors.
• get_new_results Gets the new results of a monitor since the last read.
• delete_monitor Deletes a monitor.

The installer also adds the Telem skill to ~/.cursor/skills/telem/. It tells the agent to read pages with telem_fetch, and to send a goal and a reason with each search.

Specific to Cursor

• The hook keeps each chat’s searches together. It links every search and page read to your chat and the prompt, so the console shows one conversation.
• Why Cursor searched. The hook records the model’s thinking during each turn, and sends the thinking that led to each search or page read. Until a Telem call takes it, the thinking waits in ~/.telem/plugins/cursor-telem/cursor-thoughts.json, which only you can read.
• Options come from the files. The hook reads the .telem/telem.json of the first folder open in Cursor, then ~/.telem/telem.json, then the TELEM_* variables. With no folder open, it reads only ~/.telem/telem.json. It sends your options with every search and page read. providerOverrides is not sent. It is not yet confirmed that Cursor gives your shell’s environment to the hook, so set options in a file.
• Cloud agents are not set up. The installer sets up the agent that runs on your computer. Cursor’s cloud agents do not run your user hook file. If a cloud agent has a Telem server, its searches carry no options or reasoning, and the console does not keep them together.
• The Cursor CLI. The agent command reads the same ~/.cursor/mcp.json, so it gets the Telem tools. It is not yet confirmed that it runs the hook.

If something goes wrong

• Every call gets 401: the Authorization header in ~/.cursor/mcp.json is missing or has an old key. Run the installer again, or edit the header.
• A second Telem server, plugin-telem-telem, fails with 401: Cursor also loads Claude Code’s plugins. If you use Claude Code with the Telem plugin, Cursor shows that plugin’s server too, but it does not fill in the plugin’s key. Your own telem server is not affected, so you can ignore the failing one.
• The console does not keep a chat’s searches together, or shows no reasoning: the hook did not run. Check that node is on the PATH that Cursor runs with, and that ~/.cursor/hooks.json has the two Telem handlers. Then restart Cursor. The search still runs, without your options.

Update and remove

To update, run the installer again. It replaces the hook and the skill, and updates the key in ~/.cursor/mcp.json. You can keep the key you already have.

What the installer writes for Cursor

File	What it holds
~/.cursor/mcp.json	The telem server, with your key in its Authorization header. Only you can read the file.
~/.cursor/hooks.json	Two Telem handlers: preToolUse sends your options and the reasoning with each Telem call, and afterAgentThought records the model’s thinking. Your own handlers stay.
~/.cursor/skills/telem/	The Telem skill.
~/.telem/plugins/cursor-telem/	The hook scripts, and the thinking of the current turn until a Telem call takes it.

To remove Telem:

1. In ~/.cursor/mcp.json, remove mcpServers.telem.
2. In ~/.cursor/hooks.json, remove the preToolUse and afterAgentThought handlers that run cursor-telem/hooks/lineage.mjs.
3. Delete the ~/.cursor/skills/telem and ~/.telem/plugins/cursor-telem folders.
4. Restart Cursor. Cursor then has no Telem server, skill or hook.

What the installer changed outside Cursor’s config

File	What it holds	To undo
~/.telem/credentials.json	Your key	Delete it if no other Telem integration uses it.
~/.telem/telem.json	Your Telem options	Delete it if no other Telem integration uses it.

Learn more

Configuration

Set the tier, the providers and auto-routing in one file, for Cursor and your other agents.

Parameters

Every option, the values it takes, and which setting wins.

Search parameters

What each search option does, from tiers to date windows.

Fetch parameters

Choose the fetch provider and tier, or read pages live.