Connect an MCP server and the agent can call its tools — local commands and remote HTTP / SSE servers both work.

MCP (Model Context Protocol) is an open protocol that lets the agent call tools provided by external MCP servers. Connect a server and its tools show up in the agent's tool list.

Connecting a server

Desktop: Settings → Agent → MCP. After adding a server you can see its connection status and tools.

CLI:

neox mcp add brave-search --env BRAVE_API_KEY=your-key npx -y @modelcontextprotocol/server-brave-search
neox mcp test brave-search      # connect once and list its tools

For a remote server use --transport http --url <address> (or sse). Inside the interactive UI, /mcp opens a management menu.

Config files

Two scopes, shared by the desktop app and the CLI:

Scope	Location
User	The `mcp` section of `~/.neox/config.json`
Project	`<project>/.neox/mcp.json`

{
  "servers": [
    {
      "id": "brave-search",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "your-key" },
      "enabled": true
    }
  ]
}

(In the user-level config.json, wrap it in "mcp": { ... }.)

Field	Description
`id`	Unique identifier, also the tool-name prefix
`name`	Display name, optional
`transport`	`stdio` (local command), `http` (Streamable HTTP) or `sse`
`command` / `args`	Launch command and arguments for stdio
`url`	Address for http / sse
`env`	Environment variables for the server process, passed as is — no `${VAR}` expansion
`enabled`	`false` keeps the config but doesn't load it
`autoConnect`	`true` connects at startup; otherwise it connects when first used
`allowlist` / `denylist`	Allow only / block some of this server's tools

A repository's mcp.json needs approval first

.neox/mcp.json is a file in the project repository, and a single stdio entry in it can run any command on your machine. So servers that come from a repository are not connected by default:

Desktop — in Settings → Agent → MCP these servers show "From this project · not approved". Clicking "Approve" first lists the command and environment variables it will run; confirm to record the approval and connect.
CLI — neox mcp list shows unapproved servers; once you've checked one, run neox mcp trust <id>.

Both share the same approval record in your user config.

Approval is tied to the server's configuration, so if the repository changes its command you'll need to approve it again. Servers you add yourself at user level are not affected.

CLI subcommands

Command	What it does
`neox mcp list`	List all servers, flagging unapproved ones
`neox mcp add <id> [options] <command...>`	Add one; options are `--scope` (`user` or `workspace`), `--transport`, `--url`, `--env K=V`, `--yes`
`neox mcp remove <id>`	Remove
`neox mcp enable <id>` / `disable <id>`	Enable / disable
`neox mcp connect <id>`	Connect and cache the tool list
`neox mcp test <id>`	Test the connection and list tools
`neox mcp trust <id>` / `untrust <id>`	Approve / revoke a repository server

Adding a stdio server shows the command it will run and asks for confirmation; in non-interactive environments (CI) pass --yes.

Tool names

A server's tools appear to the agent as mcp__<server id>__<tool name>, e.g. mcp__brave-search__brave_web_search.

Availability

	Supported
Desktop	✓
CLI	✓

Security

An MCP server is a separate process and does not run inside the Neox sandbox; what it can do is up to the server itself. Only connect servers you trust.