> 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
The Telys MCP server (`telys mcp`) speaks JSON-RPC 2.0 over stdio and exposes exactly **five** tools: `telys_search`, `telys_add`, `telys_create_collection`, `telys_list_collections`, and `telys_stats`. 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
Server not detected — client can't find telys on PATH
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.
Env block not delivered — server starts but uses the wrong store
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.
Tools missing or incomplete
The client connected but shows fewer than the five 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 exactly five tools: `telys_search`, `telys_add`, `telys_create_collection`, `telys_list_collections`, `telys_stats`. There are no update, delete, or tune tools over MCP by design.
Stale virtualenv — client launches an old or broken telys
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.
## Next steps
Once the client connects, tune where each client reads and writes with scopes and env.
MCP configuration & scoping
User vs project scope, memory paths, and per-client config.
Next: [MCP configuration & scoping](/mcp/configuration-and-scoping.md)
---
# 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/troubleshooting/mcp-client.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.