> 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/troubleshooting/mcp-client.md).

# MCP client

Fix an MCP client that won't connect to Telys — server not detected on PATH, env block not delivered, tools missing, or a stale virtualenv.

The Telys MCP server (`telys mcp`) speaks JSON-RPC 2.0 over stdio and exposes **19** tools — a full replica of the SDK's text surface (CRUD, filtered queries, lexical search, maintenance, and a repo auto-indexer; full list in the [MCP overview](https://docs.telys.ai/mcp/overview.md#the-tools-at-a-glance)). When a client (Claude Desktop, Cursor, Codex) can't see them, it usually can't spawn the `telys` process or spawned one that can't reach your config. The usual culprits follow.

{% hint style="info" %}
GUI apps don't inherit your shell's `PATH`. A `telys` that runs fine in your terminal is often invisible to a desktop client — which is why the fixes below lean on absolute paths and explicit `env` blocks.
{% endhint %}

## Quick check

```bash
which telys              # the absolute path your client should launch
telys mcp status         # is a server registered for this client/scope?
telys mcp                # run the stdio server by hand; it should start and wait
```

## Errors and fixes

<details>

<summary>Server not detected — client can't find <code>telys</code> on PATH</summary>

The client launches `telys mcp` as a subprocess. Desktop apps start from a minimal environment without your shell `PATH`, so a bare `telys` command isn't found.

**Cause:** the client config uses `"command": "telys"` but the app can't resolve it.

**Fix:** let Telys write the config (it records an absolute path), or set the command to the absolute path from `which telys`.

```bash
which telys                     # e.g. /Users/you/.local/bin/telys
telys mcp install               # writes config for all clients (user scope) with a resolved path
telys mcp install --client cursor --scope project
```

```json
{
  "mcpServers": {
    "telys": {
      "command": "/Users/you/.local/bin/telys",
      "args": ["mcp"]
    }
  }
}
```

Prefer `telys mcp install` — it handles the path and the client-specific config file. Then fully restart the client.

</details>

<details>

<summary>Env block not delivered — server starts but uses the wrong store</summary>

The MCP server reads its memory location from `$TELYS_MEMORY_PATH` (default `~/.telys/memory`). Without an `env` block, the server won't see the store or credentials you expect, so it looks "connected but empty".

**Cause:** the client config omits `env`, so the subprocess runs with only the app's environment.

**Fix:** add an explicit `env` block to the server entry.

{% code title="mcp server config" %}

```json
{
  "mcpServers": {
    "telys": {
      "command": "/Users/you/.local/bin/telys",
      "args": ["mcp"],
      "env": {
        "TELYS_MEMORY_PATH": "/Users/you/.telys/memory",
        "TELYS_HOME": "/Users/you/.telys"
      }
    }
  }
}
```

{% endcode %}

Restart the client after editing. Confirm the path is the one you ingested into.

</details>

<details>

<summary>Tools missing or incomplete</summary>

The client connected but shows fewer than the 19 Telys tools, or none.

**Cause:** the client cached an older handshake, connected to a half-started server, or is pointed at a `telys` that failed to launch.

**Fix:** confirm the server runs standalone, then fully restart the client to re-run tool discovery.

```bash
telys mcp                # should start and block, waiting for JSON-RPC on stdio
telys mcp status         # confirm the registration for your client/scope
```

You should see 19 tools — search and query (`telys_search`, `telys_search_lexical`, `telys_get`, `telys_repo_search`), CRUD (`telys_add`, `telys_upsert`, `telys_update`, `telys_delete`), collection admin (`telys_create_collection`, `telys_list_collections`, `telys_stats`, `telys_ids`, `telys_count`), maintenance (`telys_compact`, `telys_build_ivf`, `telys_build_lexical`, `telys_tune`), and the repo auto-indexer (`telys_index_repo`, `telys_workspace_info`). The full table is in the [MCP overview](https://docs.telys.ai/mcp/overview.md#the-tools-at-a-glance).

</details>

<details>

<summary>Stale virtualenv — client launches an old or broken <code>telys</code></summary>

If `telys` lives in a virtualenv that was upgraded, moved, or deleted, the absolute path baked into the client config can point at a stale interpreter.

**Cause:** the recorded command path no longer resolves to a working `telys`.

**Fix:** re-install into a stable location, re-register with the MCP client, and restart.

```bash
pipx install telys                 # stable, isolated install (preferred)
which telys                        # confirm the new absolute path
telys mcp uninstall                # remove the stale registration
telys mcp install                  # re-register with the fresh path
```

`pipx` keeps `telys` in one predictable place, avoiding most stale-path problems with GUI clients.

</details>

## Next steps

Once the client connects, tune where each client reads and writes with scopes and env.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>MCP configuration &#x26; scoping</strong></td><td>User vs project scope, memory paths, and per-client config.</td><td><a href="https://docs.telys.ai/mcp/configuration-and-scoping.md">Config &amp; scoping</a></td></tr><tr><td><strong>Install the MCP server</strong></td><td>Register Telys with Claude, Cursor, Codex, and Qwen Code.</td><td><a href="https://docs.telys.ai/mcp/install-server.md">Install the server</a></td></tr></tbody></table>

Next: [MCP configuration & scoping](https://docs.telys.ai/mcp/configuration-and-scoping.md)
