Skip to main content
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

The CLI launches the server itself and talks to it over standard input and output. Everything after -- is the command Cortex launches:
The -- matters. Without it, flags meant for the server (-v, -m) are parsed as Cortex flags.
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.
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.

​
Manage servers

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:
/mcp-auth covers the same ground without leaving the session.

​
Diagnose a server that will not connect

​
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:
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:

​
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:
Entries take allow, ask or deny, like the rest of the permission table. See Permission policy for how those rules combine with the approval policy and the sandbox, and Tools the agent uses 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:
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. 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.