Niluxv1.0.11
/mcp

MCP servers.

The Model Context Protocol is an open standard for connecting AI agents to external tools and services. Register an MCP server with Nilux and its tools become available in every session — the agent discovers them automatically and uses them when relevant.

Why MCP

Instead of building integrations one at a time, MCP gives you a single interface. Any MCP-compliant server — whether it talks to GitHub, a database, Slack, or your internal deploy tool — exposes its capabilities as tools that Nilux can call. Built-in tools and MCP tools look the same to the model.

Adding a server

Two options: the CLI command, or editing the JSON file directly.

bash
# Stdio server (runs as a child process)
$nilux mcp add --transport stdio --scope project my-server -- npx -y @org/mcp-server
# SSE/HTTP server (connects via URL)
$nilux mcp add --transport sse --scope user my-api http://localhost:8080/mcp
# With env vars and custom headers
$nilux mcp add -t http -e API_KEY=xxx -H "Authorization: Bearer ..." my-server https://example.com/mcp

Or edit .mcp.json in your project root:

json
{
  "mcpServers":  {
    "my-server":  {
      "command":  "npx",
      "args":  ["-y", "@org/mcp-server"],
      "env":  { "API_KEY":  "your-key-here" }
    },
    "my-api":  {
      "url":  "http://localhost:8080/mcp",
      "transport":  "sse"
    }
  }
}

Transports

Three transport types for different server architectures:

  • stdio (default) — Nilux spawns the server as a child process. Communication via stdin/stdout. Best for local tools.
  • sse — Server-Sent Events over HTTP. Server runs independently, Nilux connects to its URL.
  • http — Streamable HTTP. Similar to SSE but uses the newer MCP HTTP transport spec.

Scopes

Servers are stored at three scopes. When the same server name appears in multiple scopes, the most specific wins:

  1. ~/.nilux/settings.json — user scope. Available in every project.
  2. .mcp.json — project scope. Commit to git, share with your team.
  3. ~/.nilux/settings.local.json — local scope. Private overrides, never committed.
TIP

Use -s project when adding servers the team should share. Use -s user for personal tools that follow you across projects.

Server config options

Every server supports these fields in the JSON config:

  • command + args — for stdio servers
  • url — for network servers (sse/http)
  • transport — stdio, sse, or http
  • env — environment variables passed to the server process
  • headers — custom HTTP headers for network transports
  • allowedTools — whitelist specific tools from this server
  • deniedTools — block specific tools from this server
  • disabled — disable the server without removing its config
  • timeout — custom timeout in milliseconds (default: 30s, init: 90s)

Managing servers

From the terminal (outside a session):

bash
# List all configured servers
$nilux mcp list
# Show full config for a server
$nilux mcp get my-server
# Remove a server
$nilux mcp remove -s project my-server

Inside a session, use /mcp to view and manage connected servers interactively.

How tools appear

MCP tools are loaded as deferred tools. The agent sees their names and descriptions, but full schemas are loaded on demand when the agent decides to use one. This keeps the context window small even with dozens of MCP tools available.

You don't need to tell the agent which MCP tools to use. It reads the descriptions and picks the right one based on the task. If you want to be explicit, just mention it: "use the postgres MCP to check the schema".

Building your own

An MCP server is any program that implements the MCP JSON-RPC protocol. The official SDK makes this straightforward:

js
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new McpServer({ "name":  "my-tool" });
server.tool("deploy", { ref: z.string() }, async ({ ref }) => {
  // your logic here
  return { content: [{ type: "text", text: `Deployed ${ref}` }] };
});
const transport = new StdioServerTransport();
await server.connect(transport);

Then register it with Nilux:

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

See the MCP specification for the full protocol reference. SDKs are available for TypeScript, Python, Java, Kotlin, and C#.

← Previous · Project memoryNext · Skills →