> 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/configuration-and-scoping.md).

# Config & scoping

The Telys MCP server (`telys mcp`) is a JSON-RPC 2.0 server over stdio (protocol version `2025-06-18`), spawned by your MCP client as a child process. Because the client launches it, everything the server needs — the memory store, the runtime, and the kernel — is set through the `env` block of the client config, not your shell. This page is the reference for that config, the install scope, result wrapping, and errors.

## The tool set

The server registers **exactly five tools**. There is no update, delete, or tune tool over MCP — those live only in the SDK.

| Tool                                                        | Purpose                                      |
| ----------------------------------------------------------- | -------------------------------------------- |
| [`telys_search`](/mcp/tool-search.md)                       | Semantic + lexical search over a collection. |
| [`telys_add`](/mcp/tool-add.md)                             | Add text documents (auto-creates + saves).   |
| [`telys_create_collection`](/mcp/tool-create-collection.md) | Create a collection, partitioned by scope.   |
| [`telys_list_collections`](/mcp/tool-list-collections.md)   | List the saved collections.                  |
| [`telys_stats`](/mcp/tool-stats.md)                         | Report a collection's stats.                 |

{% hint style="info" %}
To update, tune, or build an IVF index, use the Python SDK. A Telys server (`RemoteCollection`) exposes only `delete`, `upsert`, and `compact` from these — not `update_texts`, `tune`, `apply_tuning`, `build_ivf`, or `snapshot`. See [Update records](/working-with-data/update-records.md), [Delete & compact](/working-with-data/delete-and-compact.md), and [Serving overview](/self-hosting/overview.md). MCP is the read/append surface.
{% endhint %}

## Environment

Set these in the client's `env` block. All are optional and default to your per-user store.

| Variable            | Default           | Effect on the MCP server                                                                                                      |
| ------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `TELYS_MEMORY_PATH` | `~/.telys/memory` | Directory holding the collections the tools read and write. Point separate clients at separate paths to isolate their memory. |
| `TELYS_HOME`        | `~/.telys`        | Root of all on-disk Telys state (creds, runtime, default `memory/`).                                                          |
| `TELYS_RUNTIME`     | `""` (auto)       | Force `native` or `local` runtime selection.                                                                                  |
| `TELYS_KERNEL`      | —                 | Force the native kernel library path (highest priority; `AME_KERNEL` is the legacy fallback).                                 |

See [Environment variables](/operations/environment-variables.md) for the full list and precedence.

{% code title="claude\_desktop\_config.json" lineNumbers="true" %}

```json
{
  "mcpServers": {
    "telys": {
      "command": "telys",
      "args": ["mcp"],
      "env": {
        "TELYS_MEMORY_PATH": "$TELYS_MEMORY_PATH"
      }
    }
  }
}
```

{% endcode %}

{% hint style="warning" %}
`"command": "telys"` requires the `telys` executable on the `PATH` of the process that launches the client — which for GUI apps is often **not** your shell's `PATH`. If the client cannot find it, set `command` to the absolute path from `which telys`. See [MCP client won't connect](/troubleshooting/mcp-client.md).
{% endhint %}

## Install scope: user vs project

`telys mcp install` writes the config block above into your client's configuration. `--scope` chooses **which config file** it edits — it does not change memory partitioning.

{% tabs %}
{% tab title="user (default)" icon="user" %}
Writes to the client's **user-level** configuration, so the `telys` server is available in every project for that client:

```bash
telys mcp install --client claude --scope user
```

Use this for a single personal memory store shared across your work.
{% endtab %}

{% tab title="project" icon="folder" %}
Writes to a **project-local** configuration file in the current directory, so only that project sees the server:

```bash
telys mcp install --client cursor --scope project
```

Combine with a project-local `TELYS_MEMORY_PATH` in the `env` block to give each repository its own isolated memory.
{% endtab %}
{% endtabs %}

`--client` accepts `claude`, `cursor`, `codex`, `claude-desktop`, or `all` (the default). See [Install the MCP server](/mcp/install-server.md) and [telys mcp](/cli/mcp.md).

{% hint style="info" %}
**Two different "scopes."** `--scope user|project` is about *where the client config file lives*. The `scope` partition key (from `partition_by="scope"`) is about *how records are grouped inside a collection* and is filtered with the `where` argument. They are unrelated — see [Partitions & scope keys](/understand-telys/partitions-scope-key.md).
{% endhint %}

## Result wrapping

Every tool returns its JSON payload encoded into a **single text content block**, wrapped so a tool failure never crashes the server. The success envelope:

{% code title="success.json" %}

```json
{
  "content": [
    { "type": "text", "text": "{\"collections\": [\"notes\"]}" }
  ],
  "isError": false
}
```

{% endcode %}

The `text` field is a JSON string — parse it to get the payload. Tool-specific payloads are documented on each tool's page.

## Error shape

On failure the server returns the same envelope with `isError: true` and a single text block of the form `<Type>: <message>`:

{% code title="error.json" %}

```json
{
  "content": [
    { "type": "text", "text": "ValueError: collection 'notes' does not exist (create it first)" }
  ],
  "isError": true
}
```

{% endcode %}

Common causes:

<details>

<summary><code>ValueError</code> / collection not found</summary>

The `collection` argument names a collection that is not in the active store. Confirm it with [`telys_list_collections`](/mcp/tool-list-collections.md), and check `TELYS_MEMORY_PATH` points where you expect.

</details>

<details>

<summary>Multi-key <code>where</code> filter rejected</summary>

Telys filters are `Eq` — single-column equality. A `where` object with more than one key raises an error. Pass exactly one key (`scope` for MCP-created collections). See [Filters (Eq)](/reference/filters.md).

</details>

<details>

<summary>Runtime or kernel not installed</summary>

Any collection operation needs the signed runtime, and the default embedder needs the native kernel. If either is missing the tool errors. Install and verify with `telys runtime install` then `telys runtime verify`. See [Install & runtime issues](/troubleshooting/install-and-runtime.md).

</details>

## See also

* [MCP overview](/mcp/overview.md) — what the server is and when to use it.
* [Install the MCP server](/mcp/install-server.md) — one-command setup per client.
* [telys mcp](/cli/mcp.md) — the CLI subcommand and its flags.
* [Environment & exit codes](/cli/environment-and-exit-codes.md) — environment reference for every command.


---

# 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/configuration-and-scoping.md?ask=<question>&goal=<endgoal>
```

`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.