/mcp

MCP servers.

MCP (Model Context Protocol) is an open standard for connecting AI assistants to other programs and services. An MCP server is a small program that offers tools, for example "query the database", "create an issue" or "read the latest error reports". Connect one to Nilux, and its tools work in your sessions next to the built-in ones.

Many services already offer an MCP server. Look in their documentation for "MCP".

Add a server

Use nilux mcp add in your terminal (not inside a session). There are two kinds of servers.

A server that runs on your computer is started by Nilux as a program. Put -- before the command that starts it:

bash$nilux mcp add context7 -- npx -y @upstash/context7-mcp@latest

A server on the internet is reached by its address. Give the transport with -t:

bash$nilux mcp add -t http sentry https://mcp.sentry.dev/mcp

Options:

-s user (the default) makes the server available in all your projects. -s project saves it in the project's .mcp.json, for this project only. -s local is like user, but wins over both: use it to replace a server of the same name, privately.
-t http or -t sse says how to talk to a server at an address: use http unless the service's documentation says SSE. Always give it for an address; without it the address is saved as a program to run.
-e KEY=value passes a setting, such as an API key, to a server that runs on your computer.
-H "Authorization: Bearer …" sends a header to a server at an address.

Put -e and -H after the server's name (and address), as here:

bash$nilux mcp add my-server -e API_KEY=your-key -- npx -y @org/mcp-server
$nilux mcp add -t http sentry https://mcp.sentry.dev/mcp -H "Authorization: Bearer your-token"

The server is available from the next Nilux session you start.

Manage servers

From the terminal:

bash$nilux mcp list
$nilux mcp get sentry
$nilux mcp remove sentry

To remove a project or local server, add -s project or -s local.

Inside a session, /mcp shows each server with its status and tools. There you can sign in to a server that needs it, connect, disconnect, reconnect, or switch a server off without deleting it.

Using the tools

You do not need to tell Nilux which tool to use. It reads what each tool does and picks the right one. To be specific, just say so: "use the sentry tools to find today's errors".

You may see a ToolSearch line before Nilux first uses a server's tool: it is looking up the tool's details. This keeps your conversation small even with many servers connected.

Calls to MCP tools are approved like any other action. Yes, always allow… applies to that one tool only.

A tool that takes longer than two minutes moves to the background and reports back when it is done.

The configuration files

nilux mcp add writes these files for you; you can also edit them by hand.

~/.nilux/settings.json: servers for all your projects (-s user).
.mcp.json in the project folder: servers for this project (-s project). Commit it to share them with your team.
~/.nilux/settings.local.json: also yours, for all projects, and it wins over the other two (-s local).

If a server with the same name is in more than one file, the one in settings.local.json wins, then the project's.

json{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp",
      "transport": "http"
    }
  }
}

Each server can also have:

env: settings passed to a server that runs on your computer;
headers: headers sent to a server at an address;
disabled: true to switch it off without removing it;
deniedTools: names of tools Nilux must not use from this server;
timeout: how long to wait for an answer, in milliseconds.

A server that saves files, such as screenshots, can write them to the session's scratch folder instead of your project: put ${SCRATCHPAD} in its args or env.

Build your own

An MCP server can be written in TypeScript, Python and other languages with the official SDKs. See the MCP website. Register yours like any other:

bash$nilux mcp add -s project deploy -- node ./scripts/deploy-mcp.js

Navigate

Resources