---
title: "MCP servers"
---

# MCP servers

Connect Model Context Protocol servers to the CLI, sign in to them, control their tools with rules, and load them for one run.

The CLI connects to [Model Context Protocol](https://modelcontextprotocol.io) servers and gives their tools to the agent as `mcp_<server>_<tool>`. Server prompts become slash commands named `/<server>:<prompt>`, and server resources can be browsed with the `mcp_resources` and `mcp_read_resource` tools.

## Add a server

```bash
neuralinverse mcp add files -- npx -y @modelcontextprotocol/server-filesystem ~/docs
neuralinverse mcp add docs --url https://mcp.example.com/mcp           # Streamable HTTP
neuralinverse mcp add legacy --url https://old.example.com/sse --sse   # HTTP + SSE
neuralinverse mcp add db API_TOKEN=xyz -- ./bin/db-mcp                 # with environment variables
neuralinverse mcp list
neuralinverse mcp remove files
```

Servers are written to `.neuralinverse/settings.json`; add `--user` to write to your user settings instead. `mcp list` shows each server's transport, state and number of tools.

You can also edit settings directly:

```jsonc
{
  "mcpServers": {
    "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } },
    "sqlite": { "type": "stdio", "command": "uvx", "args": ["mcp-server-sqlite", "--db-path", "./dev.db"] }
  }
}
```

`${VAR}` references are expanded from the environment in commands, arguments, `env`, URLs and headers.

## Sign in to a server

Servers that use OAuth are signed in to from the shell or in a session:

```bash
neuralinverse mcp login <name>     # opens your browser; prints the URL if it does not open
neuralinverse mcp logout <name>    # signs out and removes the stored credentials
```

In a session, `/mcp` shows status and server logs, and can sign in or out.

## For one run

| Flag | Effect |
|---|---|
| `--mcp-config <file>` | Load servers from a file of the form `{"mcpServers": {...}}` for this run (repeatable) |
| `--no-mcp` | Start no MCP servers |

## Behaviour

- Servers connect in parallel at start-up, in the background after the prompt appears; the first message waits for them. The connect timeout is `NEURALINVERSE_MCP_TIMEOUT` (default 30 seconds).
- A failing server never blocks the session. Check `/mcp` for status and logs, and `/mcp reconnect <name>` to retry.
- Tool calls time out after `NEURALINVERSE_MCP_TOOL_TIMEOUT` (default 10 minutes).
- HTTP servers fall back from Streamable HTTP to SSE automatically.
- Above `tools.deferThreshold` tools (default 40), MCP tools load on demand: the agent finds them with `find_tools`.

## Permissions

Tools that declare `readOnlyHint` are treated as read-only by the permission engine. Everything else asks unless a rule allows it:

```jsonc
{ "permissions": { "allow": ["mcp_github_*"] } }
```

Organisation governance decides each MCP call, including the server it goes to, before your rules. See [Permissions and modes](https://neuralinverse.com/docs/cli/permissions/).

Administrators can lock `mcpServers` in [managed settings](https://neuralinverse.com/docs/cli/enterprise/) so that only approved servers are used. An editor connected over ACP can add servers for its session unless managed policy locks `mcpServers`.

[Plugins](https://neuralinverse.com/docs/cli/plugins/) can bring MCP servers too; they appear as `<plugin>-<server>`.