> 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/install-server.md).

# Install the server

`telys mcp install` writes a `telys` server entry into your MCP clients' configuration, so you never hand-edit JSON. It detects the clients you have, merges in a stdio block that runs `telys mcp`, and leaves your existing servers untouched. This page covers the command, what it writes, and the manual equivalent.

## Before you install

The MCP server runs the signed native runtime, so install, sign in, and verify Telys first.

{% stepper %}
{% step %}

#### Install Telys

{% tabs %}
{% tab title="pipx" icon="terminal" %}

```bash
pipx install telys
```

{% endtab %}

{% tab title="pip" icon="python" %}

```bash
pip install telys
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}

#### Sign in and verify the runtime

```bash
telys login
telys runtime verify
```

`telys login` activates the free `telys_developer` plan and installs the runtime; add `--plan telys_pro` for commercial use. `telys runtime verify` confirms the signed runtime and kernel are present — the MCP tools need them.
{% endstep %}

{% step %}

#### Install into your clients

```bash
telys mcp install
```

With no flags this targets `--client all` at `--scope user`.
{% endstep %}
{% endstepper %}

## The install command

```bash
telys mcp install [--name NAME] [--client {claude,cursor,codex,claude-desktop,all}] [--scope {user,project}]
```

| Flag       | Default | Purpose                                                                                                                            |
| ---------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `--name`   | `telys` | Server key written into the client config. Change it to run more than one Telys server (for example, a second store).              |
| `--client` | `all`   | Which client to configure: `claude`, `cursor`, `codex`, `claude-desktop`, or `all`.                                                |
| `--scope`  | `user`  | `user` writes a home-level config shared across projects; `project` writes a config in the current directory that a repo can ship. |

The command is idempotent: re-running it updates the `telys` entry in place instead of duplicating it, and preserves other servers.

### What it writes, per client

Each entry runs the local `telys` executable with `args: ["mcp"]` over stdio. The target file depends on the client and scope.

| `--client` value | Client                      | Where the entry is written                                    |
| ---------------- | --------------------------- | ------------------------------------------------------------- |
| `claude-desktop` | Claude Desktop app          | `claude_desktop_config.json` (user scope only)                |
| `cursor`         | Cursor                      | `~/.cursor/mcp.json` (user) or `./.cursor/mcp.json` (project) |
| `claude`         | Claude Code                 | Claude Code's user or project MCP config                      |
| `codex`          | Codex CLI                   | `~/.codex/config.toml`                                        |
| `all`            | every detected client above | each client's own config file                                 |

{% hint style="info" %}
Not every client supports both scopes. Claude Desktop is user-only; Cursor, Claude Code, and Codex support a project-scoped file you can commit alongside your repo. The installer does not write VS Code — configure it by hand from [Cursor & VS Code](/mcp/client-cursor-vscode.md).
{% endhint %}

## Check status

`telys mcp status` reports which clients have the server entry and where.

```bash
telys mcp status
```

```
Telys MCP command: telys mcp
  registered     claude-desktop (user): ~/Library/Application Support/Claude/claude_desktop_config.json
  registered     cursor (user): ~/.cursor/mcp.json
  not registered codex (user): ~/.codex/config.toml
```

Pass `--name` to check a differently named server.

## Uninstall

`telys mcp uninstall` removes the `telys` entry, leaving the rest of each config intact. It mirrors the install flags.

```bash
telys mcp uninstall                       # remove from every client (user scope)
telys mcp uninstall --client cursor       # remove from Cursor only
telys mcp uninstall --scope project       # remove the project-scoped entry
```

## Configure by hand

To edit the config yourself — or for a client the installer does not support — add this block to the client's MCP configuration. The `env` block is optional; include `TELYS_MEMORY_PATH` only for a store other than `~/.telys/memory`.

{% code title="mcp config (generic stdio)" %}

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

{% endcode %}

{% hint style="warning" %}
`"command": "telys"` requires the `telys` executable on the `PATH` of the process that launches the client — which for GUI apps on macOS is often **not** your shell's `PATH`. If the client cannot find it, set `command` to the absolute path from `which telys` (for example `/Users/you/.local/bin/telys` for a pipx install).
{% endhint %}

## Expected result

After `telys mcp install`, `telys mcp status` shows `registered` for each targeted client, and each config file contains a `telys` server entry. Restart or reload the client (see the client pages); its tool menu then lists the five `telys_*` tools.

## Next steps

<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>Claude Desktop</strong></td><td>Config paths, restart, and the PATH gotcha.</td><td><a href="/pages/ouxpwobSuCAZG78N8iU9">/pages/ouxpwobSuCAZG78N8iU9</a></td></tr><tr><td><strong>Cursor &#x26; VS Code</strong></td><td>Editor MCP config and reload.</td><td><a href="/pages/Xi6UuKyPqX5ZPtarQnMw">/pages/Xi6UuKyPqX5ZPtarQnMw</a></td></tr><tr><td><strong>Other MCP clients</strong></td><td>Codex and any stdio client.</td><td><a href="/pages/um8yppzglq28k2m65DiG">/pages/um8yppzglq28k2m65DiG</a></td></tr><tr><td><strong>telys mcp reference</strong></td><td>Every flag for the mcp subcommands.</td><td><a href="/pages/ybkX8RDOAgjAOVltcNoS">/pages/ybkX8RDOAgjAOVltcNoS</a></td></tr></tbody></table>


---

# 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/install-server.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.