Integrations

MCP server

Telem hosts an MCP server at https://mcp.telem.ai/mcp (Streamable HTTP). Connect any MCP client to it, and the client gets the Telem search, page-reading and monitor tools.

A private deployment has its own MCP url. Use it in place of https://mcp.telem.ai/mcp in the examples on this page. The installer’s copy-paste snippet uses it when you install with --mcp-url https://mcp.example.com/mcp, for example.

Using Claude Code, Codex, Grok Build, Muse, VS Code, Cursor, Devin Desktop, OpenCode, OpenClaw, Pi, DeepSeek Harness or Hermes? Use its own integration. It adds what a plain MCP connection cannot, such as query lineage from the conversation and your .telem/telem.json settings. Find yours on Integrations.

Using Claude or ChatGPT? Add Telem there as a connector, and sign in with your Telem account: see Claude or ChatGPT.

Before you begin

An MCP client that speaks Streamable HTTP. It either sends a Telem API key in an Authorization header, or signs in with your Telem account: see Sign in instead of a key.

Create a Telem API key

Open your project
API keys
Issue API key

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

Open the console

Never paste a key into a chat with your AI client. Every path below sets it for you.

Install

Connect your MCP client to Telem

Add the server. Put your key in place of your-telem-api-key.

claude mcp add --transport http telem https://mcp.telem.ai/mcp --header "Authorization: Bearer your-telem-api-key" --header "X-Telem-Auto-Routing: accuracy"

Check the connection. telem is in the list.
Terminal window
```
claude mcp list
```

The Claude Code plugin sets up the same tools with one installer command, and adds query lineage.

Add the server to ~/.codex/config.toml. Put your key in place of tlm_….

[mcp_servers.telem]
url = "https://mcp.telem.ai/mcp"
http_headers = { Authorization = "Bearer tlm_…", X-Telem-Auto-Routing = "accuracy" }

Check the connection. telem is in the list.
Terminal window
```
codex mcp list
```

The Codex install writes this table for you, and also adds the Telem plugin.

Add the server where your client keeps its remote MCP servers. This block uses the common mcpServers convention. Your client’s docs say where it goes.

{
  "mcpServers": {
    "telem": {
      "url": "https://mcp.telem.ai/mcp",
      "headers": {
        "Authorization": "Bearer tlm_…",
        "X-Telem-Auto-Routing": "accuracy"
      }
    }
  }
}

Check the connection. Your client lists telem and its tools.

Test your key from the command line

curl -s https://mcp.telem.ai/mcp \
  -H "Authorization: Bearer $TELEM_API_KEY" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}'

A valid key gets the server’s initialize result. A missing or rotated key gets a 401.

A client that supports MCP sign-in (OAuth) needs only the URL, https://mcp.telem.ai/mcp, and no Authorization header. When it connects, it opens a Telem page in your browser. Sign in with your Telem account, pick a project if you have more than one, and select Allow. Telem then creates an API key for that client in the project. The key’s name starts with MCP: and the client’s address, and it expires after 90 days. The client never sees the key. To disconnect the client, revoke its key in the console.

Claude and ChatGPT connect this way. Not every client can sign in to Telem. VS Code, for one, cannot: give it a key.

Claude Code: add the server with no key, then run /mcp in Claude Code, pick telem, and authenticate.

claude mcp add --transport http telem https://mcp.telem.ai/mcp

Codex: add the server with no key, then sign in.

codex mcp add telem --url https://mcp.telem.ai/mcp
codex mcp login telem

This sets up only the tools. The Claude Code and Codex integrations also add query lineage and your options, and they use a key.

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

8 tools

monitor_create Creates a monitor. Its agent keeps the results that match.
monitor_list Lists your monitors that have an agent.
monitor_get Gets a monitor and its agent.
monitor_agent Gets the agent: its status, its plan and what it found.
monitor_changes Reads what the agent found, change by change.
monitor_pause Pauses a monitor.
monitor_resume Resumes a paused monitor.
monitor_delete Ends a monitor.

telem_search also takes an optional context: one or two sentences in which the model says why it makes this search and what it needs from it. The tool tells the model to leave out secrets and private data. Telem stores the text with the call, in the same field that the SDKs set with context. Today it does not change the results. In the console, it shows as the agent’s reasoning for that call. telem_fetch does not take it.

How the tools behave

Each tool has a title and hints for MCP clients. telem_search, telem_fetch, telem_providers, telem_session_history, monitor_list, monitor_get, monitor_agent and monitor_changes are marked read-only, so a client that honors the hint, such as Codex, runs them without asking. monitor_create, monitor_pause, monitor_resume and monitor_delete change your monitors, so a client may ask before it runs them.

The earlier monitor tools, create_monitor, list_monitors, get_new_results and delete_monitor, are retired. Your client still lists them for now. They change nothing, and answer with the tool to use instead.

The description of telem_search tells the model to prefer it over another public-web search tool that does the same job. It tells the model to use another tool only in three cases: you ask for it, Telem is unavailable, or this server does not expose a capability. This is only guidance. An MCP server cannot turn off a host’s built-in tools the way a plugin can.

Every telem_search result starts with a Telem session id. The model sends that id back on later searches for the same task, as the tool descriptions teach it.

Each result names the provider that found it, as in [exa] URL: https://…. A provider that failed gets one line of its own, such as [serpapi] failed: upstream 500, and a provider whose results could not be read gets [tavily] no rows (<reason>).

What each tool’s description says

Tool	Description
`telem_search`	The main tool for public-web search. One call sends the query to several providers. It returns all their results in one normalized response. So you usually do not need a single-index search tool, such as a host’s built-in web search.
`telem_fetch`	Read the full text of web pages by URL. Each call takes a small batch of http(s) URLs and fetches them together. Search returns snippets and never reads pages. This tool reads the pages.
`telem_providers`	List the search providers configured on the Telem backend: name, type, a short description, and which ones run when the user’s Telem config names none. (default) marks the providers that run with auto-routing off, or with it on for a query on an unranked topic; (auto-routed) marks the ones auto-routing can pick for a ranked topic.
`telem_session_history`	Show the earlier searches of a Telem search session: one numbered line per search, with its status and queries.
`monitor_create`	Create a monitor: Telem runs a query on a schedule, and the monitor’s agent keeps the results that match. Each run is billed to your account. The model sets how long the monitor runs, `ttl`: 30 days unless you ask for another time. The tool sets no webhook: set one with an SDK or the API, which gives you its secret once.
`monitor_list`	List your key’s monitors that have an agent, with the status of each agent.
`monitor_get`	Get one monitor and its agent: the agent’s status, its plan version, when it runs next, and the newest change you can read.
`monitor_agent`	Get the monitor’s agent: its status, its plan, when it runs next, and how many items it found.
`monitor_changes`	Read what the agent found, oldest first, one change per line. The model sends `next_cursor` back to read on, so no change comes twice.
`monitor_pause`	Pause a monitor until it is resumed.
`monitor_resume`	Resume a paused monitor. Each run is billed to your account.
`monitor_delete`	End a monitor, so that it stops running.

Configuration

Two headers apply to every connection:

Header	Value
`Authorization`	`Bearer` and your API key. Required, unless your client signs in.
`X-Telem-Auto-Routing`	`accuracy` or `off`. Optional: without it, auto-routing is on. The installer sets it. See Auto-routing.

On the hosted server, auto-routing is on by default. Telem chooses the providers for each search. To turn it off for a connection, send the header X-Telem-Auto-Routing: off. The Claude Code, Codex, Grok Build, Muse, VS Code, Cursor and Devin Desktop integrations send your autoRouting setting for you. See Auto-routing.

More headers set the search tier, the search providers and the fetch options for every call on the connection.

Set the tier and the providers with headers

The hosted server runs the deployment’s defaults. The tools give the model no setting that changes what a search or a page read costs, so you set the tiers and the providers on the connection instead, with headers next to Authorization. For example, in the headers block of the JSON setup above:

{
  "Authorization": "Bearer tlm_…",
  "X-Telem-Tier": "extended",
  "X-Telem-Providers-Include": "exa,tavily",
  "X-Telem-Fetch-Tier": "extended"
}

For telem_search:

Header	Sets
`X-Telem-Tier`	The search tier: `minimalist`, `default`, `extended` or `max`.
`X-Telem-Providers-Include`	Only these providers, comma-separated. With auto-routing on, Telem chooses among them. See Providers.
`X-Telem-Providers-Exclude`	Never these providers, comma-separated.

For telem_fetch:

Header	Sets
`X-Telem-Fetch-Providers`	The fetch providers to try, comma-separated, in your order. One name means no failover.
`X-Telem-Fetch-Tier`	The fetch tier: `minimalist`, `default`, `extended` or `max`. A tier above `extended` is lowered to `extended`.
`X-Telem-Fetch-No-Cache`	`1` reads every page live.

See Pinning the fetch provider.

The search headers apply to every telem_search on the connection, and the fetch headers to every telem_fetch. Neither changes the other tool.
Values are not case-sensitive, and a blank header means not set.
When you send both provider headers, the excluded names are taken out of the include list.
The server checks the headers when your client connects. An unknown tier, an X-Telem-Fetch-No-Cache value other than 1, or a pair of provider headers that leaves no provider refuses the connection with HTTP 400 and a message that names the header, such as X-Telem-Tier must be one of: minimalist, default, extended, max.
Provider names are checked on each call instead: an unknown name fails the search or the page read.
With the Claude Code, Codex, Grok Build, Muse, VS Code, Cursor or Devin Desktop integration, a setting in your .telem/telem.json wins over the same header.