> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP servers in the CLI

> Connect Model Context Protocol servers to the CLI: the three transports, tokens, tool names, permissions, and the server panel

The Cortex CLI is a Model Context Protocol client. Connecting an MCP server adds its tools to the set the agent can call, alongside the built-in tools. That is how you give a session a capability the CLI does not ship with: the agent sees the server's tools as ordinary tools, and every one of them passes the same approval and sandbox boundary as a built-in tool.

This page covers adding a server over each of the three transports, how tokens are handled, the commands for listing, enabling and removing servers, how to diagnose one that will not connect, how the server's tools are named and how to control them, and where the configuration ends up on disk.

## Add a server

<Tabs>
  <Tab title="A local process">
    The CLI launches the server itself and talks to it over standard input and output. Everything after `--` is the command Cortex launches:

    ```bash theme={null}
    cortex mcp add myserver -- npx @example/mcp-server
    cortex mcp add myserver -- python -m my_server
    cortex mcp add myserver --env API_HOST=<hostname> -- node server.js -v
    ```
  </Tab>

  <Tab title="A remote server (HTTP)">
    For a server that speaks streamable HTTP, give it a URL:

    ```bash theme={null}
    cortex mcp add myapi --url https://<host>/mcp
    cortex mcp add myapi --url https://<host>/mcp --bearer-token-env-var MY_API_TOKEN
    ```

    `--bearer-token-env-var` takes the **name** of an environment variable. Cortex reads the token from it at runtime, so the token itself never lands in a config file.
  </Tab>

  <Tab title="A remote server (SSE)">
    For a server that streams events:

    ```bash theme={null}
    cortex mcp add myevents --sse https://<host>/sse
    cortex mcp add myevents --sse https://<host>/sse --sse-bearer-token-env-var MY_API_TOKEN
    ```
  </Tab>
</Tabs>

<Warning>
  The `--` matters. Without it, flags meant for the server (`-v`, `-m`) are parsed as Cortex flags.
</Warning>

URLs pointing at `localhost`, `127.0.0.1` or private network ranges are rejected by default. Pass `--allow-local` when you are deliberately talking to a development server.

<Note>
  A server you add is code you have chosen to run, and its tools act with the authority the session gives them. Nothing establishes who published a server. The CLI verifies a SHA-256 checksum for its own release downloads, and even there a checksum detects corruption, not independent publisher identity: checksums are not signatures.
</Note>

## Manage servers

```bash theme={null}
cortex mcp list                  # alias: ls
cortex mcp list --all            # include disabled servers
cortex mcp list --json
cortex mcp get <server>
cortex mcp enable <server>
cortex mcp disable <server>
cortex mcp rename <old> <new>
cortex mcp remove <server>       # alias: rm
```

Inside a session, `/mcp` opens the manager, `/mcp-tools` lists the tools each server exposes, and `/mcp-reload` re-reads the configuration after you have edited it. `Ctrl+E` opens the manager directly.

## Sign in to a server that requires it

Some servers will not expose their tools until you have authorised the CLI with them:

```bash theme={null}
cortex mcp auth <server>
cortex mcp auth list
cortex mcp logout <server>
cortex mcp logout --all
```

`/mcp-auth` covers the same ground without leaving the session.

## Diagnose a server that will not connect

```bash theme={null}
cortex mcp debug <server>
cortex mcp debug <server> --test-auth
cortex mcp debug <server> --timeout 60 --no-cache
cortex mcp debug <server> --json
```

## Read the server panel

The panel header counts what is live, for example `MCP servers · 2 of 4 connected`. Each row is the server name, its tool count, and its state. A connected row is prefixed with a tick and reads `<server>   12 tools · connected`, with the count coming from the server itself. The other states look like this:

```
⠇ <server>   authenticating…
× <server>   failed — token expired · r to reconnect
```

A row still in progress shows a braille spinner and the word `authenticating…`. A failed row is marked with `×` and carries the reason and the recovery key inline. A row with no glyph has not been attempted, and the selected row is prefixed `> `. `token expired` is one reason among others, so read the row rather than assuming the cause.

The footer strip on that panel is:

```
 Enter:details  |  r:reconnect  |  a:add server  |  Esc:close
```

## Tool names and permissions

A tool from server `myserver` called `search` is presented as `mcp__myserver__search`. That prefix is what you use when filtering with `--enabled-tools` or `--disabled-tools`, and what appears in the `permission.mcp` table:

```toml theme={null}
[permission.mcp]
"myserver" = "allow"
"risky-server" = "ask"
```

Entries take `allow`, `ask` or `deny`, like the rest of the permission table. See [Permission policy](/cli/policy) for how those rules combine with the approval policy and the sandbox, and [Tools the agent uses](/cli/tools) for the built-in names.

MCP is also how browser work gets done: Cortex ships no built-in browser or desktop-automation tool. Connect a server that provides those tools, and they pass the same boundary as any other tool call. `/browser` reports whether such a server is connected and names it.

## Where the configuration lives

`cortex mcp add` writes into the global `config.toml` under `mcp_servers`:

```toml theme={null}
[mcp_servers.myserver]
enabled = true

[mcp_servers.myserver.transport]
type = "stdio"
command = "npx"
args = ["@example/mcp-server"]

[mcp_servers.myserver.transport.env]
API_HOST = "internal"
```

```toml theme={null}
[mcp_servers.myapi]
enabled = true

[mcp_servers.myapi.transport]
type = "http"
url = "https://<host>/mcp"
bearer_token_env_var = "MY_API_TOKEN"
```

```toml theme={null}
[mcp_servers.myevents]
enabled = true

[mcp_servers.myevents.transport]
type = "sse"
url = "https://<host>/sse"
```

`type` is one of `stdio`, `http`, `sse` or `web_socket`, and `enabled` defaults to `true`. There is no `cortex mcp add` flag for `web_socket`; it is configuration only.

Servers you add from inside the session are stored separately, as one file per server in the CLI's own data directory rather than in `config.toml`. So a server that `cortex mcp list` shows but `config.toml` does not mention was almost certainly added that way. See [Data locations](/cli/data-locations).

The sources describe MCP servers as a source of **tools**. Whether a server can also contribute prompts or resources to a session is not established, and no limit on the number of servers or tools is published.

## Related

* [Tools the agent uses](/cli/tools)
* [Permission policy](/cli/policy)
* [CLI plugins](/cli/plugins)
* [Configuration](/cli/configuration)
* [Data locations](/cli/data-locations)