Setup
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_URLto your base URL, the app host your users open (for examplehttps://nano.example.com), and omitNANOSIEM_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.
| Var | Required | Default | Notes |
|---|---|---|---|
NANOSIEM_API_URL | Yes | none (throws if missing) | Base URL of the API. A trailing slash is stripped. |
NANOSIEM_API_KEY | Yes | none (throws if missing) | Sent as the X-API-Key header on every request. |
NANOSIEM_SEARCH_URL | No | falls back to NANOSIEM_API_URL | Search 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.
| Capability | Permissions | Access |
|---|---|---|
Search (search, explain_query, get_field_values) | search:execute | read |
| Saved and shared searches | search:view, search:save, search:share | read / write |
Raw SQL (search_sql) | search:sql | read |
| Alerts | alerts:view | read |
| Cases: read | cases:view | read |
| Cases: write | cases:create, cases:edit, cases:close, cases:assign, cases:comment | write |
| Notebooks: read | notebooks:view | read |
| Notebooks: write | notebooks:create, notebooks:edit, notebooks:share | write |
| Dashboards | dashboards:view, dashboards:create, dashboards:edit | read / write |
| Detections | detections:view | read |
| MITRE | mitre:view | read |
| Entities and risk | risk:view | read |
Risk reset (reset_entity_risk) | risk:clear | destructive |
Enrichment (lookup_ip) | enrichments:view | read |
| Prevalence | prevalence:view | read |
| Audit trail | audit:view | read |
| Org context | settings:view | read |
| Parsers: read | log_sources:view, parser_repositories:view | read |
| Parsers: author and publish | log_sources:create, log_sources:edit, log_sources:deploy, parser_repositories:sync, parser_repositories:import | write |
| Routing and onboarding | source_configs:view, source_configs:create, source_configs:edit, source_configs:deploy, credentials:create, credentials:use | write |
| Recon | hunts:profile_write | write |
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_URLand 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