Add a local server
You need an existing reviewed MCP server, such as a local server.mjs. Replace example paths with actual reviewed absolute paths. add can overwrite a configuration with the same name; check existing entries first.
lurus mcp add local-docs --command node --args /absolute/path/server.mjs --cwd /absolute/path/project --timeout 15000 --project
lurus mcp list
add saves the configuration but does not start the server. Without --project, it saves globally; with that flag, for the current project. The corresponding .lurus/settings.json is:
{
"mcpServers": {
"local-docs": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/server.mjs"],
"cwd": "/absolute/path/project",
"env": { "DOCS_MODE": "readonly" },
"timeout": 15000,
"trust": false,
"includeTools": [],
"excludeTools": []
}
}
}
For global use, put the same structure in ~/.lurus/settings.json. Review the executable, arguments, environment variables and working directory. DOCS_MODE only has an effect if the server supports it; it does not enforce read-only access through the CLI. Start a new session and review the consent request before allowing the project server to start.
HTTP, SSE and headers
Fictional endpoints, not for unreviewed execution:
lurus mcp add remote-docs --url https://example.invalid/mcp --type http --timeout 15000
lurus mcp add legacy-docs --url https://example.invalid/sse --type sse --project
Supply exactly one of --command or --url. Without --type, a URL defaults to http and a local command to stdio. --args <args...>, --env <KEY=VALUE...> and --cwd are local-only; --header <KEY=VALUE...> is remote-only. Keys and values are split at the first =. Never put real secrets in examples, shell history or repositories.
The CLI stores header values securely and writes headerRefs to settings instead of plaintext secrets. References are bound to scope, server and project path; do not create or edit them manually. Use headers only for deliberately nonsensitive values. Headers are checked for invalid characters. --timeout requires a positive integer in milliseconds; configuration accepts a positive finite number. The default is 15,000 ms.
Complete options and filters
CLI add: --command, --url, --type, --args, --env, --cwd, --header, --timeout, --trust, --project. Settings also covers headers, headerRefs, includeTools, excludeTools.
Filter using actual unqualified server tool names:
{
"includeTools": ["search_docs", "read_doc"],
"excludeTools": ["read_doc"]
}
Merge this fragment into the existing server object; it is not a complete settings file. An empty includeTools list does not restrict available tools. excludeTools takes precedence, so only search_docs remains available here. Use exact, unqualified tool names, not globs or names such as mcp__server__tool. The server must actually expose those tools.
Startup consent versus trust
Project servers require consent before starting. Startup consent does not grant trusted tool status: project servers remain untrusted even with trust: true. Global trust: true or --trust explicitly grants trust to that global source; it is not proof of safety. Tool, permission and role filters still apply; custom agents do not gain MCP tools.
A project object replaces a same-name global server entirely, not nested merging. Rejecting the project source does not guarantee global fallback startup. URLs must use http(s); existing metadata/link-local checks are not comprehensive SSRF protection. Review destinations and disclosure.
Stdio receives fixed safe child ENV plus configured env. LURUS_MCP_PASS_ENV adds comma-separated names, making values fully visible to the server. Keys/tokens are not generally inherited automatically.
Runtime management and removal
/mcp
/mcp restart local-docs
/mcp refresh-tools
/mcp lists status. Restart reconnects, does not automatically refresh visible schemas. refresh-tools updates the manifest; a cache miss can follow. Start a new session after adding servers or changing their configuration.
lurus mcp remove local-docs --project
lurus mcp remove remote-docs
lurus mcp list
Use the scope matching the entry. remove deletes configuration and related header references where possible; inspect any reported errors. Validation errors, settings errors and unknown removal entries exit with code 1.
Troubleshooting
If the server does not start, check consent, command, absolute paths, working directory and timeout. For incorrect tool selection, check include/exclude names and use refresh-tools. Project servers deliberately lack global trust. For invalid header references, use the CLI in the correct scope rather than manipulating stored data. Approve missing environment variables individually, not all secrets.
Next: permissions, settings.