Tool Reference
Every nano-investigator tool, MCP prompt and MCP resource, with permissions and access level
Look up the tools and permissions for @nano-rs/investigator-mcp-server 0.1.16 (main at e5b4043). The server registers 91 tools in 14 groups, five MCP prompts, and 11 MCP resources.
Columns:
- Access: Read has no side effects. Write creates or changes data. Destructive removes, closes or resets something and can't be undone, so the agent should confirm first.
- Permission: what the API key needs. Each tool also publishes its requirement in MCP
_metaunderio.nano/permission-requirements, so clients can show it before calling.
Parameters are required unless marked (opt).
Search and schema (9)
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
search | Run an nPL query. The primary search tool. | query, start_time; end_time, limit (100), source type (opt) | Read | search:execute |
search_sql | Raw SQL SELECT against ClickHouse (read-only identity; audit rows need audit:view) | sql; start_time, end_time, limit (opt) | Read | search:sql |
get_schema | UDM column inventory (not the OCSF field list) | category, include_ext (opt) | Read | search:view, search:execute |
explain_query | Show how an nPL query compiles, without running it | query, start_time; end_time (opt) | Read | search:execute |
get_field_values | Top values for a field in a query scope | field, start_time; query, end_time, limit (opt) | Read | search:execute |
list_saved_searches | List saved searches | none | Read | search:view |
get_saved_search | One saved search | id | Read | search:view |
save_search | Save a query | name, query; query_mode, visibility (opt) | Write | search:save |
create_shared_search | Build a shareable UI link for a query and time range | query; query_mode, time range (opt) | Write | search:share |
Alerts (3)
Alerts can't be changed through the server. Triage happens by attaching an alert to a case.
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
list_alerts | List alerts with filters | all (opt): status, severity, rule_id, assigned_to, limit (50), offset | Read | alerts:view |
get_alert | Full alert, with matched events and ai_triage_hints | id | Read | alerts:view |
get_alert_counts | Counts by severity and status | none | Read | alerts:view |
Cases (13)
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
list_cases | List cases | all (opt): status[], severity[], assigned_to, search, tags[], limit, offset | Read | cases:view |
get_case | Full case | id | Read | cases:view |
review_case | Case, wall and every linked notebook in one call. Use it first when resuming a case. | id (id or case number) | Read | cases:view, notebooks:view |
get_case_stats | Counts by status and severity, average resolution | none | Read | cases:view |
get_related_cases | Similar past cases (shared entities, rules, techniques) | id | Read | cases:view |
create_case | Create a case | title, severity; description, priority, assigned_to, tags[] (opt) | Write | cases:create |
update_case | Edit title, description, severity or tags | id; fields (opt) | Write | cases:edit |
change_case_status | Set status and optional disposition | id, status; disposition (opt) | Write | cases:edit; cases:close to close or reopen |
assign_case | Reassign | id, user_id | Write | cases:assign |
add_alert_to_case | Link an alert | case_id, alert_id; is_primary (opt) | Write | cases:edit, alerts:view |
add_case_wall_entry | Post to the case wall | case_id, entry_type (comment/ai_analysis/action_taken), content | Write | cases:comment |
merge_notebook_into_case | Copy a notebook's entries into the case notebook and archive the source as merged. If the case has no notebook, the source becomes it and is visible to everyone who can see the case. | case_id, source_notebook_id | Write | cases:view, cases:edit, notebooks:edit |
merge_cases | Merge source cases into a target; sources are closed as merged | target_case_id, source_case_ids[] | Destructive | cases:edit |
Notebooks (9)
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
list_notebooks | List notebooks | all (opt): case_id, status, limit, offset | Read | notebooks:view |
get_notebook | One notebook | id | Read | notebooks:view |
get_notebook_entries | A notebook's entries | id | Read | notebooks:view |
find_notebooks_by_reference | Notebooks that reference an alert, detection, saved search or case | reference_type, reference_id | Read | notebooks:view |
create_notebook | Create a notebook | title; visibility (opt) | Write | notebooks:create |
add_notebook_entry | Append an entry (manual_note, search_executed, ai_suggestion, ai_summary, entity_reference, an IOC marker, timeline_marker, investigation_timeline) | notebook_id, entry_type, content; source_url (opt) | Write | notebooks:edit, or cases:edit for a case notebook |
add_notebook_reference | Link a notebook to an object | notebook_id, reference_type, reference_id | Write | notebooks:edit |
update_notebook | Edit title, status or summary | id; fields (opt) | Write | notebooks:edit |
share_notebook | Change visibility | id, visibility; group_ids[] (opt) | Write | notebooks:share |
Dashboards (7)
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
get_dashboard_schema | The dashboard document format. Read before authoring. | none | Read | none |
validate_dashboard | Check a dashboard document locally | dashboard | Read | none |
dashboard_panel_query | Run a panel query the way the panel will | query, query_mode, start_time; end_time (opt) | Read | dashboards:view + search:execute (nPL) |
list_dashboards | List dashboards | scope (my/all) (opt) | Read | dashboards:view |
get_dashboard | One dashboard | id | Read | dashboards:view |
create_dashboard | Create a dashboard | dashboard | Write | dashboards:create |
update_dashboard | Replace a dashboard | id, dashboard | Write | dashboards:edit |
Detections and MITRE (5)
The server reads detections; it doesn't write them. Use nanodac to author rules.
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
list_detections | List rules | all (opt): severity, mode, enabled | Read | detections:view |
get_detection | Full rule: nPL, MITRE, ai_triage_hints, schedule | id | Read | detections:view |
get_detection_matches | Recent matches for a rule | id | Read | detections:view |
get_mitre_technique | ATT&CK data, optionally one technique | id (opt) | Read | mitre:view |
get_mitre_coverage | Detection coverage and gaps | none | Read | mitre:view, detections:view |
Risk (5)
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
get_risky_entities | Top entities by risk | all (opt): window, entity_type, min_score, limit (20) | Read | risk:view |
get_risk_overview | Entity counts by risk level (24h and 7d) | none | Read | risk:view |
get_entity_risk_timeline | Risk over time for one entity | entity; entity_type (opt) | Read | risk:view |
get_entity_risk_activity | Recent risk activity for several entities | entities[] (entity, entity_type) | Read | risk:view |
reset_entity_risk | Clear an entity's accumulated risk. The reason is audited. | entity, reason; entity_type (opt) | Destructive | risk:clear |
Enrichment (2)
Threat-intel matches are stamped onto events at ingest as enrichments[] records, so you find them with search (for example enrichments.type="threat_intelligence"). See Enrichment field reference.
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
get_entity_context | Composite pivot: geolocation (IPs) and risk timeline | entity_type, value | Read | risk:view |
lookup_ip | Geolocation and ASN for one IP | ip | Read | enrichments:view |
Prevalence (3)
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
get_prevalence | How common one hash or domain is (IPs aren't accepted) | type (hash/domain), value | Read | prevalence:view |
get_rare_artifacts | Artifacts seen on few hosts | all (opt): type (hash_md5/hash_sha256/domain/ip_address), window, limit (50), offset | Read | prevalence:view |
get_new_artifacts | Artifacts first seen recently | all (opt): type, since, limit (50), offset | Read | prevalence:view |
System (4)
| Tool | Purpose | Key params | Access | Permission |
|---|---|---|---|---|
get_source_types | Log sources with data | none | Read | any of search:execute, detections:view, log_sources:create, source_scopes:view |
get_org_context | Org profile: industry, internal ranges, critical assets, hours | none | Read | settings:view or settings:ai |
health_check | Calls /health. Usable only when NANOSIEM_API_URL points straight at the API; behind the edge the path serves the web app | none | Read | none |
get_audit_trail | Query the audit log, including this key's own actions | all (opt): user_id, action, resource_type, start_time, end_time, limit (50) | Read | audit:view |
Parsers (23)
See Build parsers for the workflow and the OCSF output contract.
| Tool | Purpose | Access | Permission |
|---|---|---|---|
list_log_sources | List parsers | Read | log_sources:view |
get_log_source | Full parser: VRL, metadata, flags | Read | log_sources:view |
validate_vrl | Compile-check VRL | Read | log_sources:view |
test_parse_sample | Run VRL on one sample line | Read | log_sources:view |
test_parse_live | Parse recent real events with new and published VRL | Read | log_sources:view, search:execute |
get_log_source_draft_status | Unpublished changes, active version | Read | log_sources:view |
get_log_source_health | Event counts, freshness, health_status | Read | log_sources:view |
get_log_source_deployments | Rollout history and errors | Read | log_sources:view |
create_log_source | Save a new parser as a working copy | Write | log_sources:create |
update_log_source | Edit a working copy (doesn't go live) | Write | log_sources:edit |
publish_log_source | Promote the working copy and roll it out. The step that makes an edit live. | Write | log_sources:deploy |
deploy_log_source | Re-push the published version | Write | log_sources:deploy |
undeploy_log_source | Take a parser offline | Destructive (stops parsing for that source) | log_sources:deploy |
list_source_config_types | Transport drivers and match-field presets | Read | source_configs:view |
list_source_configs | Configured transports | Read | source_configs:view |
check_rule_reachability | Check a planned routing rule | Read | source_configs:view |
create_routing_rule | Route matching events to a parser | Write | source_configs:edit |
deploy_source_config | Redeploy a transport | Write | source_configs:deploy (+ credentials:use with a credential) |
undeploy_source_config | Take a transport offline | Destructive (stops that ingest path) | source_configs:deploy |
list_parser_repositories | Connected parser repositories | Read | parser_repositories:view |
list_repository_parsers | Browse a repository | Read | parser_repositories:view |
sync_parser_repository | Refresh a repository | Write | parser_repositories:sync |
import_parser | Import a repository parser as a working copy | Write | parser_repositories:import, source_configs:edit |
Onboarding (4)
Set up pull-source transports (Kafka, AWS S3/SQS, GCP Pub/Sub).
| Tool | Purpose | Access | Permission |
|---|---|---|---|
onboarding_requirements | What each transport needs | Read | none |
import_credential_from_file | Read a credential file from the local disk (inside your home or working directory) and store it encrypted | Write | credentials:create |
create_credential | Store a credential | Write | credentials:create |
create_source_config | Create a transport, optionally with routing rules | Write | source_configs:create (+ credentials:use with a credential) |
Recon (4)
Profile your log estate and propose hunts.
| Tool | Purpose | Access | Permission |
|---|---|---|---|
hunt_build_census | Step 1: census of which telemetry is live | Read | hunts:profile_write (or hunts:manage) |
hunt_huntable_surface | Step 2: what can be hunted with that telemetry | Read | hunts:profile_write (or hunts:manage) |
hunt_save_profile | Save the estate profile | Write | hunts:profile_write (or hunts:manage) |
hunt_propose_drafts | Create draft hunts with opening nPL queries | Write | hunts:profile_write (or hunts:manage) |
Tools that change state
Everything marked Write or Destructive above. The ones that can't be undone:
merge_cases: source cases are closed as merged.reset_entity_risk: the entity's accumulated risk is cleared.undeploy_log_sourceandundeploy_source_config: ingest for that source stops until redeployed.
Also take care with publish_log_source (changes how new events are parsed) and import_credential_from_file (reads a file from the machine the server runs on).
MCP prompts
Prompts are workflows the agent follows, not tools.
investigate_alert(alert_id;depth(opt) quick/standard/deep): read the alert and its detection'sai_triage_hints, assess false vs true positive, enrich entities, search for related activity, check related cases, recommend. See Investigate alerts.hunt_entity(entity,entity_type;time_range(opt), default-24h): context, assessment, then a type-specific deep dive. See Hunt.hunt_campaign(description;time_range(opt), default-7d): plan from a hypothesis, run 3–5 queries, enrich hits, write a hunt report.morning_briefing(hours(opt), default 12): alerts, case load, risky entities, noisy or silent rules and health, as a prioritized shift summary. See Triage & cases.build_parser(source type;sample_log(opt)): the validate-first parser loop. See Build parsers.
MCP resources
| URI | Content |
|---|---|
nanosiem://reference/npl | nPL reference |
nanosiem://reference/vrl-parsers | VRL authoring guide (UDM output contract in 0.1.16) |
nanosiem://reference/playbooks/{type} | Investigation playbooks: brute_force, lateral_movement, data_exfil, malware, phishing, insider_threat, generic |
nanosiem://schema/udm | Legacy field reference (not the OCSF schema) |
nano://sql-guide | SQL guide for search_sql (UDM logs table) |
For OCSF fields, point the agent at OCSF field reference instead of the last two.