nano SIEM
Agents & MCPInvestigator

Setup

Supported in:Self-hosted

Add the nano-investigator MCP server to your agent with npx, configure it against your nano deployment, and verify the connection

Configure nano-investigator so your coding agent can call nano with a scoped API key. The server runs locally over stdio; npx fetches the published package without a source build.

The package is published as @nano-rs/investigator-mcp-server.

Requirements

  • Node.js >= 20.0.0 (provides npx)
  • A running nano instance reachable from where the server runs

Install

Add the MCP server to your agent

Add an entry to your MCP config (a project-level .mcp.json, or your agent's MCP settings). npx resolves the published package on first launch, so the only values you supply are the environment variables:

{
  "mcpServers": {
    "nano-investigator": {
      "command": "npx",
      "args": ["-y", "@nano-rs/investigator-mcp-server"],
      "env": {
        "NANOSIEM_API_URL": "https://nano.example.com",
        "NANOSIEM_API_KEY": "your-api-key"
      }
    }
  }
}

The key is a placeholder. The URL depends on where nano runs:

  • Docker Compose or Kubernetes: set NANOSIEM_API_URL to your base URL, the app host your users open (for example https://nano.example.com), and omit NANOSIEM_SEARCH_URL. The edge routes /api/search* to the search service. Don't use the separate ingest hostname.
  • Split services: set both, with the API on port 3000 and search on port 3002.

Restart your agent

Restart the agent so it picks up the new MCP server. In Claude Code, run /mcp to confirm nano-investigator shows as connected.

Environment variables

The server reads exactly three environment variables. No others are consulted.

VarRequiredDefaultNotes
NANOSIEM_API_URLYesnone (throws if missing)Base URL of the API. A trailing slash is stripped.
NANOSIEM_API_KEYYesnone (throws if missing)Sent as the X-API-Key header on every request.
NANOSIEM_SEARCH_URLNofalls back to NANOSIEM_API_URLSearch service. Used for /api/search* calls.

.env loading

The server also loads .env and .env.local, walking up to three parent directories from where it starts. It never overrides a variable that is already set in the environment, so an explicit value in your MCP config or shell always wins.

Request timeout

Every API request uses a fixed 60000 ms timeout. This is not configurable through an environment variable.

API key permissions

The server authenticates with a single API key in the X-API-Key header. A nano key carries an explicit permission list set when you create it — it does not inherit a role — and the backend checks every request against that list. Scope the key to exactly the capabilities you'll use; a leaked least-privilege key can't do more than the agent could.

Permissions by capability

get_dashboard_schema, validate_dashboard, onboarding_requirements and health_check need no permission. Every other tool lists its exact requirement in the Tool Reference.

CapabilityPermissionsAccess
Search (search, explain_query, get_field_values)search:executeread
Saved and shared searchessearch:view, search:save, search:shareread / write
Raw SQL (search_sql)search:sqlread
Alertsalerts:viewread
Cases: readcases:viewread
Cases: writecases:create, cases:edit, cases:close, cases:assign, cases:commentwrite
Notebooks: readnotebooks:viewread
Notebooks: writenotebooks:create, notebooks:edit, notebooks:sharewrite
Dashboardsdashboards:view, dashboards:create, dashboards:editread / write
Detectionsdetections:viewread
MITREmitre:viewread
Entities and riskrisk:viewread
Risk reset (reset_entity_risk)risk:cleardestructive
Enrichment (lookup_ip)enrichments:viewread
Prevalenceprevalence:viewread
Audit trailaudit:viewread
Org contextsettings:viewread
Parsers: readlog_sources:view, parser_repositories:viewread
Parsers: author and publishlog_sources:create, log_sources:edit, log_sources:deploy, parser_repositories:sync, parser_repositories:importwrite
Routing and onboardingsource_configs:view, source_configs:create, source_configs:edit, source_configs:deploy, credentials:create, credentials:usewrite
Reconhunts:profile_writewrite

Minimal vs full key

Read-only investigation: hunt, triage and review with no changes:

[
  "search:view", "search:execute",
  "alerts:view",
  "cases:view",
  "notebooks:view",
  "dashboards:view",
  "detections:view",
  "mitre:view",
  "risk:view",
  "enrichments:view",
  "prevalence:view"
]

Add log_sources:view and parser_repositories:view to browse parsers read-only.

Full: adds case, notebook and dashboard writes and parser authoring:

[
  "search:view", "search:execute", "search:save", "search:share",
  "alerts:view",
  "cases:view", "cases:create", "cases:edit", "cases:close", "cases:assign", "cases:comment",
  "notebooks:view", "notebooks:create", "notebooks:edit", "notebooks:share",
  "dashboards:view", "dashboards:create", "dashboards:edit",
  "detections:view", "mitre:view", "risk:view", "enrichments:view", "prevalence:view",
  "audit:view",
  "log_sources:view", "log_sources:create", "log_sources:edit", "log_sources:deploy",
  "parser_repositories:view", "parser_repositories:sync", "parser_repositories:import"
]

Leave out risk:clear unless the agent should be able to reset risk scores. Add the source_configs:* and credentials:* permissions only if the agent will set up pull sources.

Create a scoped key

In the nano UI go to Settings → API Keys and create a key with just the permissions above. You can only grant permissions your own account holds. You can also call the API directly (the caller needs apikeys:create):

curl -X POST https://nano.example.com/api/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name":"mcp-investigator","permissions":["search:view","search:execute","..."],"expires_at":"2026-12-31T00:00:00Z"}'

Pass the returned key as NANOSIEM_API_KEY.

Verify it works

Once the server shows as connected, ask the agent something small that needs the API and the key, for example "how many alerts fired in the last 24 hours?" (get_alert_counts). A count back confirms the URL, the key and its permissions.

health_check calls /health. Behind nano's edge (the base URL) that path serves the web app, so health_check returns a usable result only when NANOSIEM_API_URL points straight at the API service (port 3000).

Troubleshoot

Need help with these checks? Contact support with the request ID and time with timezone.

Use the response status to check the connection and key:

  • 401: the key is wrong or expired. Re-check NANOSIEM_API_KEY.
  • 403: the key lacks a permission. The error names the endpoint; add the permission from the table above.
  • Connection errors: re-check NANOSIEM_API_URL and that the host is reachable from where the server runs.

What's next

  • Triage: work the alert queue and open cases
  • Investigate: run an alert investigation end to end
  • Hunt: hunt entities and campaigns
  • Tool Reference: every tool, prompt, and resource

On this page