> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/mcp/overview.md). # Overview Run Telys as a Model Context Protocol server so AI clients like Claude Desktop and Cursor can search and write on-device memory through 19 tools covering the full memory surface. `telys mcp` runs Telys as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server over stdio, exposing the full Telys memory surface — 19 tools — to any MCP client. Point Claude Desktop, Cursor, Codex, or your own agent at it and the model gains a durable, on-device memory it can search, write, maintain, and index in natural language — no code, nothing leaving the machine. Introspection (`initialize`/`tools/list`) needs no credentials; tool execution requires the one-time free `telys login` (free community license) — fully offline thereafter. ```bash telys mcp ``` The command starts a JSON-RPC 2.0 server named `telys` on stdin/stdout, speaking protocol version `2025-06-18`. It runs in the foreground, prints nothing, and waits for a client. You rarely run it by hand — the client spawns it from the config on the client pages. Pass `--path` to override where memory lives (see below). {% hint style="info" %} The MCP server drives the same signed native runtime as the SDK, so install and verify the runtime first. Run `telys login` (or `telys runtime install`), then `telys runtime verify`. Without the runtime, every tool call errors. See [Verify your install](/start-here/verify-install.md). {% endhint %} ## The store and the embedder The server reads and writes one on-disk memory directory and uses one built-in embedder. Both are fixed so an assistant works with zero configuration. | Setting | Value | How to change it | | ---------------- | -------------------------------------------- | ------------------------------------------------------------------------- | | Memory directory | `$TELYS_MEMORY_PATH`, else `~/.telys/memory` | Set `TELYS_MEMORY_PATH` in the client's `env`, or pass `--path` in `args` | | Default embedder | `AlgentaMultigramEmbedder` (384-d hint) | Not configurable over MCP — use the SDK for other embedders | | Partition key | `scope` (see auto-created collections below) | `partition_by` argument on `telys_create_collection` | The default embedder is lexical (multigram-hash) and needs the native kernel that ships with the runtime. Its dimension comes from the kernel; `384` is a hint, not a hard constant. For dense or bring-your-own embedders, drive Telys from the [SDK](/quickstarts/quickstart-first-collection.md) — the MCP surface is deliberately fixed. ## The tools at a glance The server registers 19 tools — a full replica of the SDK surface that makes sense for a text-mode LLM caller: CRUD, filtered queries, lexical search, compaction / IVF / tuning, plus a repo auto-indexer. | Tool | What it does | Required arguments | Returns | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------- | | [`telys_search`](/mcp/tool-search.md) | Semantic + lexical search over a Telys memory collection | `collection`, `query` | `{ collection, query, hits: [{ id, score, metadata? }] }` | | [`telys_add`](/mcp/tool-add.md) | Add text documents to a Telys memory collection (created if absent) | `collection`, `texts` | `{ added, collection }` | | [`telys_create_collection`](/mcp/tool-create-collection.md) | Create a Telys memory collection | `name` | `{ created, dim, partition_by }` | | [`telys_list_collections`](/mcp/tool-list-collections.md) | List Telys memory collections | — | `{ collections: [...] }` | | [`telys_stats`](/mcp/tool-stats.md) | Stats for a Telys memory collection | `collection` | `{ collection, stats: {...} }` | | `telys_upsert` | Add-or-replace text rows by id (versioned update; never a duplicate physical row) | `collection`, `texts`, `ids` | `{ upserted, collection }` | | `telys_update` | Replace the vector/metadata of EXISTING ids by re-embedding new texts | `collection`, `texts`, `ids` | `{ updated, collection }` | | `telys_delete` | Tombstone rows by external id so they no longer appear in queries | `collection`, `ids` | `{ deleted, collection }` | | `telys_ids` | Return live external ids in a collection, optionally scoped by a `where` filter | `collection` | `{ collection, ids: [...] }` | | `telys_count` | Return the live row count (post-tombstone) for a collection, optionally `where`-scoped | `collection` | `{ collection, count }` | | `telys_get` | Exact row lookup by external id (no similarity search); for auto-indexed repo rows it re-reads the exact source slice from disk | `collection`, `ids` | `{ collection, rows: [{ id, found, metadata?, text? }] }` | | `telys_search_lexical` | On-device BM25 lexical search (requires the collection to have been created with `lexical=True` + `telys_build_lexical` run) | `collection`, `query` | `{ collection, query, hits: [{ id, score, metadata? }] }` | | `telys_compact` | Flush tombstones + merge delta segment into the base layout | `collection` | `{ compacted }` | | `telys_build_ivf` | Build per-partition IVF indexes; calibrates nprobe to a recall floor | `collection` | `{ ivf_built, min_rows, target_recall }` | | `telys_build_lexical` | Fit BM25 lexical index over retained tokens (needs `lexical=True` at create-time) | `collection` | `{ lexical_built, k1, b }` | | `telys_tune` | Produce (and optionally apply) a TuningPlan via the collection's Tuner | `collection` | `{ collection, plan }` | | `telys_index_repo` | Walk a repo directory (respects `.gitignore` on git checkouts), chunk each text file, and ingest into a collection — idempotent + incremental | — | `{ status, collection, repo_id, files_tracked, ... }` | | `telys_repo_search` | Search the auto-indexed repo collection; re-indexes the server workspace on every call, so results are always fresh | `query` | `{ collection, query, index_status, hits }` | | `telys_workspace_info` | Report the server's configured workspace, repo\_id, indexed collection, and file count | — | `{ workspace, repo_id, collection, files_tracked, persistent_index }` | `telys_search` also takes an optional `top_k` (default `5`) and a `where` filter. The filter is a single-key equality object, e.g. `{"tenant_id": "acme"}` — no multiple keys, ranges, or boolean operators. The SDK exposes the same equality model through [`Eq`](/reference/filters.md). `telys_add` takes optional `ids` and `metadata` arrays; an auto-created collection uses `partition_by="scope"` and is saved to disk. Every mutating tool — `telys_add`, `telys_upsert`, `telys_update`, `telys_delete`, `telys_compact`, `telys_build_ivf`, and `telys_build_lexical` — persists the store to disk after the operation. ## How a call looks on the wire A client initializes the session, then calls a tool by name with its arguments: {% code title="tools/call request" %} ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "telys_search", "arguments": { "collection": "notes", "query": "vector database", "top_k": 3 } } } ``` {% endcode %} Every result uses the standard MCP content envelope: the tool's JSON payload is returned as a `text` block, and `isError` reports success: {% code title="tools/call result" %} ```json { "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "{\"collection\":\"notes\",\"query\":\"vector database\",\"hits\":[{\"id\":\"doc-1\",\"score\":0.83,\"metadata\":{\"scope\":\"default\"}}]}" } ], "isError": false } } ``` {% endcode %} On failure, `isError` is `true` and the `text` block carries a `": "` string (for example `ValueError: collection 'notes' does not exist (create it first)`). Clients surface that string as the tool result, so the model can read and react to the error. ## When to use MCP vs the SDK Use MCP when a person talks to an AI assistant that should remember and recall across turns and sessions. Use the SDK when your own code needs full control. {% tabs %} {% tab title="Use MCP" icon="plug" %} * Give Claude Desktop, Cursor, or Codex long-term memory it manages itself. * Natural-language, no-code: the model picks the tool and fills the arguments. * The full memory surface — CRUD, filtered queries, lexical search, maintenance, and repo auto-indexing — with every mutating tool persisted to disk. * Fully on-device and offline after the one-time free `telys login` (device authorization); no API key in the client config. Start at [Install the MCP server](/mcp/install-server.md). {% endtab %} {% tab title="Use the SDK" icon="python" %} * You need raw-vector `add`/`search`, snapshots, or `apply_tuning`. * You want dense or bring-your-own embeddings, or precise [`Eq`](/reference/filters.md) filtering. * You are building an application, batch pipeline, or a remote `serve` deployment. Start at [Quickstart: your first collection](/quickstarts/quickstart-first-collection.md). {% endtab %} {% endtabs %} Both share the same on-disk format, so a collection built over MCP is readable from the SDK and vice versa — point both at the same [memory directory](/operations/environment-variables.md). ## Next steps
Install the MCP serverWire Telys into every client with one command.Install the server
Claude DesktopAdd Telys to Claude on macOS or Windows.Claude Desktop
Tool: telys_searchThe search tool, argument by argument.telys_search
Configuration & scopingChoose where memory lives and how it is shared.Config & scoping
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.telys.ai/mcp/overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.