> 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

Reference for the Telys MCP server — environment configuration, user vs project install scope, result wrapping, the error shape, and the exact tool set.

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 **19 tools** — a full replica of the SDK surface that makes sense for a text-mode LLM caller. Every mutating tool persists the store to disk after the operation.

* **Search & query:** [`telys_search`](https://docs.telys.ai/mcp/tool-search.md), `telys_search_lexical`, `telys_get`, `telys_repo_search`
* **Write & CRUD:** [`telys_add`](https://docs.telys.ai/mcp/tool-add.md), `telys_upsert`, `telys_update`, `telys_delete`
* **Collection admin:** [`telys_create_collection`](https://docs.telys.ai/mcp/tool-create-collection.md), [`telys_list_collections`](https://docs.telys.ai/mcp/tool-list-collections.md), [`telys_stats`](https://docs.telys.ai/mcp/tool-stats.md), `telys_ids`, `telys_count`
* **Maintenance:** `telys_compact`, `telys_build_ivf`, `telys_build_lexical`, `telys_tune`
* **Repo auto-index:** `telys_index_repo`, `telys_workspace_info`

The full table with arguments and return shapes is in [MCP overview](https://docs.telys.ai/mcp/overview.md#the-tools-at-a-glance).

{% hint style="info" %}
To update, upsert, delete, tune, or build indexes, use the tools above — they cover the SDK's text surface. The SDK adds raw-vector `add`/`search`, `snapshot`, and `apply_tuning` on top; a self-hosted server (`RemoteCollection`) mirrors the text surface minus `update_texts`, `tune`, and `apply_tuning`. See [Update records](https://docs.telys.ai/working-with-data/update-records.md), [Delete & compact](https://docs.telys.ai/working-with-data/delete-and-compact.md), and [Serving overview](https://docs.telys.ai/self-hosting/overview.md).
{% 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](https://docs.telys.ai/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](https://docs.telys.ai/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`, `qwen`, or `all` (the default). See [Install the MCP server](https://docs.telys.ai/mcp/install-server.md) and [telys mcp](https://docs.telys.ai/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](https://docs.telys.ai/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`](https://docs.telys.ai/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)](https://docs.telys.ai/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](https://docs.telys.ai/troubleshooting/install-and-runtime.md).

</details>

## See also

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