MCP tools reference

The 46 Model Context Protocol tools Korva exposes to AI assistants over stdio JSON-RPC. Tools are partitioned across three permission profiles — agent (41), readonly (17), admin (46) — selected via KORVA_MCP_PROFILE.

Updated: 2026-04-30

Korva implements the Model Context Protocol version 2024-11-05 over stdio JSON-RPC 2.0. Every supported IDE talks to the Vault using this protocol. The same Vault server speaks to humans over HTTP on :7437 and to AI agents over MCP on stdin/stdout simultaneously.

Permission profiles

The set of tools exposed depends on KORVA_MCP_PROFILE:

Profile	Tools	Use case
`agent`	19	AI assistant in active development. Default.
`readonly`	8	Untrusted clients — search and read-only context
`admin`	22	Admin tooling. Adds `vault_delete`, `vault_bulk_save`.

Search & context tools (agent + readonly)

Tool	Description	Key inputs
vault_search	FTS5 full-text search with compact / why modes	`query`, `project`, `team`, `country`, `type`, `limit`, `compact`, `why`
vault_context	Restore recent observations for a project at session start	`project`, `limit`, `budget_tokens`, `delta`, `prompt`, `file_paths`, `skill_limit`
vault_timeline	Date-range query	`project`, `from` (RFC3339), `to`
vault_get	Fetch a single observation by ULID	`id`
vault_hint	Ultra-light search — id+type+title only, ~10× fewer tokens	`query`, `project`, `type`, `limit`
vault_summary	High-level summary of a project	`project`
vault_stats	Global Vault statistics	none
vault_query	Structured query (no FTS) by type/date/project	`project`, `team`, `type`, `since`, `until`, `limit`
vault_skill_match	Smart Skill Auto-Loader (Teams+)	`prompt`, `project`, `file_paths`, `limit`
vault_compress	Caveman compression of long output	`text`, `mode` (off/lite/full/ultra)
vault_pattern_mine	Detect emergent patterns (Teams+)	`project`, `max`, `min_count`
vault_code_health	A–F code health grade (Teams+)	none
vault_team_context	Skills + private scrolls for the team (Teams+)	uses session token
vault_export_lore	Export team’s private scrolls (Teams+)	`since` (RFC3339)

Write tools (agent only)

Tool	Description	Key inputs
vault_save	Save an observation, with privacy filter + dedup	`title`, `content`, `type`, `tags`, `project`, `team`, `country`, `author`, `session_id`, `dry_run`, `force`
vault_save_prompt	Save a reusable prompt template	`name`, `content`, `tags`
vault_session_start	Begin a tracked work session	`project`, `team`, `country`, `agent`, `goal`
vault_session_end	Close a session with a summary	`session_id`, `summary`
vault_sdd_phase	Read or advance the SDD phase	`project`, `phase` (optional)
vault_qa_checklist	Quality criteria for a phase + language	`phase`, `language` (go/typescript/react)
vault_qa_checkpoint	Record a QA result with gate logic	`project`, `phase`, `language`, `status`, `score`, `findings`, `notes`, `gate_passed`, `session_id`

Admin tools (admin only)

Tool	Description	Key inputs
vault_delete	Remove an observation by ULID	`id`
vault_bulk_save	Save up to 50 observations in one call	`observations[]`

Observation types

Every save declares a type. These are filterable in search and act as hints to the model:

decision, pattern, bugfix, learning, context, antipattern, task, feature, refactor, discovery.

SDD phases (persisted in `sdd_state`)

explore → propose → spec → design → tasks → apply → verify → archive → onboard.

`vault_save` input schema

{
  "title":      "string (max 100 chars)",
  "content":    "string",
  "type":       "decision|pattern|bugfix|learning|context|antipattern|task|feature|refactor|discovery",
  "tags":       ["string"],
  "project":    "string",
  "team":       "string",
  "country":    "string",
  "author":     "string",
  "session_id": "ULID (optional)",
  "dry_run":    false,
  "force":      false
}

Returns either { "id": "ULID" } or { "deduplicated": true, "existing_id": "ULID" } if the same content_hash already exists in this session.

When to call which tool

Session start → vault_context with project, prompt, file_paths. Pulls auto_skills + recent observations.
Cheap discovery → vault_hint (10× cheaper in tokens than vault_search).
Full discovery → vault_search with optional why mode for hint reasoning.
Decision worth saving → vault_save with type=decision or type=pattern.
Long output to vault → vault_compress first, then vault_save.
End of session → vault_session_end with a one-paragraph summary.

Hybrid cloud search

vault_search?cloud=1 blends local results with the optional Hive community brain (3-second hard timeout). Local IDs always take priority. See Hive.