> 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 `telys mcp` runs Telys as a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server over stdio, exposing five curated memory 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 and write in natural language — no code, no API key, nothing leaving the machine. ```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 five tools at a glance The server registers exactly five tools. There are no update, delete, or tuning tools over MCP — those live in the SDK. | Tool | What it does | Required arguments | Returns | | ----------------------------------------------------------- | ------------------------------------------------- | --------------------- | -------------------------------------------------- | | [`telys_search`](/mcp/tool-search.md) | Semantic + lexical search over a collection | `collection`, `query` | `{ collection, query, hits: [{ id, metadata? }] }` | | [`telys_add`](/mcp/tool-add.md) | Add text documents (collection created if absent) | `collection`, `texts` | `{ added, collection }` | | [`telys_create_collection`](/mcp/tool-create-collection.md) | Create an empty collection | `name` | `{ created, dim, partition_by }` | | [`telys_list_collections`](/mcp/tool-list-collections.md) | List saved collections | — | `{ collections: [...] }` | | [`telys_stats`](/mcp/tool-stats.md) | Report stats for one collection | `collection` | `{ collection, stats: {...} }` | `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. ## 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\"}]}" } ], "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. * A small, safe surface — search and add, plus create/list/stats. No destructive tools. * Fully on-device and offline; 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 vector search, `update`, `delete`, tuning, IVF builds, or snapshots. * 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./pages/YhKfmMzkSFdHe5MaQYMG
Claude DesktopAdd Telys to Claude on macOS or Windows./pages/ouxpwobSuCAZG78N8iU9
Tool: telys_searchThe search tool, argument by argument./pages/MCot2Px9N71YmDCmVoPk
Configuration & scopingChoose where memory lives and how it is shared./pages/WSNXqM7PJEas18L3bBPP
--- # 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.