nkapp mcp

Start the Nanokit MCP (Model Context Protocol) server on stdio so an AI agent host can drive this project through typed tools. The server offers read tools, config-declaring tools and plan-gated apply tools. It has no destructive tools. The subcommands manage the agent approval store and read the agent audit trail.

For the concepts (tool catalog, plan-then-apply, approvals, the agent: policy, what is refused by design), see The MCP Server.

nkapp mcp [--cwd <path>]
nkapp mcp list | approve <id> | deny <id> | audit [options]

nkapp mcp

Runs the server in the foreground and speaks JSON-RPC 2.0 over stdin/stdout. You normally don't run it by hand: your agent host spawns it.

Flag	Type	Default	Description
--cwd <path>	string	current directory	Project directory to serve. One server process serves exactly one project.

• stdout carries protocol frames only. Every diagnostic goes to stderr.
• The server opens no port and starts no listener.
• agent.enabled: false in nanokit.yml makes it refuse to start and exit with code 1.

Register it (Claude Desktop / any mcpServers host):

{
  "mcpServers": {
    "nanokit": {
      "command": "nkapp",
      "args": ["mcp", "--cwd", "/abs/path/to/project"]
    }
  }
}

Claude Code:

claude mcp add nanokit -- nkapp mcp --cwd /abs/path/to/project

Subcommands

All subcommands are local. They open no SSH connection, make no network call, and need no account. With --json, each one prints exactly one JSON document on stdout.

mcp list

List this project's agent approval requests, newest first.

nkapp mcp list [--cwd <path>] [--all] [--json]

Flag	Default	Description
--cwd <path>	current directory	Project directory.
--all	off	Also show settled requests (consumed, denied, expired).
--json	off	Machine-readable output.

mcp approve <id>

Grant one use of an approval request, bound to the exact request it was filed for. The request is shown in full first, including the exact command string and where it runs for a command-bearing write. You are then asked y/N. A non-interactive run without -y is refused.

nkapp mcp approve <id> [--cwd <path>] [-y] [--json]

After you approve, the agent re-issues the identical call, and it passes once.

mcp deny <id>

Refuse an approval request. The refusal is recorded and the agent is told.

nkapp mcp deny <id> [--cwd <path>] [-y] [--json]

mcp audit

Read the agent audit trail (.nanokit/mcp/audit.jsonl plus its one rotation), newest first. A damaged line is counted, never fatal, and output is secret-redacted again on the way out.

nkapp mcp audit [--cwd <path>] [--tool <name>] [--decision <d>] [-e <env>] [--session <id>] [-n <n>] [--json]

Flag	Default	Description
--cwd <path>	current directory	Project directory.
--tool <name>	all	Only records for this tool.
--decision <d>	all	allowed, denied, approval-required or approved.
-e, --env <env>	all	Only records for this environment.
--session <id>	all	Only records from this server session, or cli for your own approve/deny decisions.
-n, --tail <n>	50	Show at most N records.
--json	off	Machine-readable output.

Examples:

nkapp mcp list
nkapp mcp approve apv_3f9c2a71d04e8b65   # id format: apv_ + 16 hex digits
nkapp mcp audit --decision denied -n 20
nkapp mcp audit --tool deploy -e production --json

Environment variables

Variable	Effect
NANOKIT_MCP_PREAUTH=<project>:<tool>[,<tool>]	Pre-authorizes the named tools for unattended runs. The project segment must equal the project name, and wildcards are not accepted. It never overrides a human deny and never covers a write to a command-bearing field.

Files

Path	Content
.nanokit/mcp/audit.jsonl	Every call, allowed or denied. Mode 0600, rotated at 10 MB.
.nanokit/mcp/approvals.json	The approval store. Mode 0600.
.nanokit/mcp/plans/<planId>.json	Single-use plan handles (10-minute TTL). Mode 0600.

All of them live under .nanokit/, which nkapp init adds to .gitignore.