Nika as an MCP server

nika mcp serves the read-only oracle over stdio — the in-binary MCP server every wired client talks to. Its contract is one sentence:

Agents can inspect freely, execute deliberately. The oracle validates and teaches; running a workflow stays on the CLI, where --max-cost-usd, the permits boundary and the trace file live.

The released binary serves stdio by default. Streamable HTTP also ships on 0.120.1: nika mcp --transport http (POST JSON-RPC, origin-gated, loopback on port 8123 by default). Widening --bind beyond loopback is on you: put TLS + auth in front first. Either transport, there is no write tool and no way to make the oracle execute anything. That is the design, not a gap: generation and repair belong to the authoring skill, execution belongs to a human-gated nika run.

Start it

No binary yet? brew install supernovae-st/tap/nika — other paths (script, Docker) in installation. Then every client uses the same two fields:

{ "command": "nika", "args": ["mcp"] }

nika wire <client> writes this stanza into the right config file. Targets on the released binary include cursor · vscode · windsurf · claude · claude-desktop · codex · gemini · qwen · opencode · hermes · zed · continue · cline · lmstudio · junie · grok · kimi (and detected / all). For any other MCP-capable client, paste the stanza into its server config — see per-client wiring.

The 9 tools

Projected from the live wire (tools/list), never hand-counted:

tool	what it answers
`nika_check`	Statically audit a workflow (schema · DAG · CEL · effects · permits · cost) before running it — findings, or a clean bill.
`nika_explain`	Teach one `NIKA-XXXX` error code: cause, category, and the fix form.
`nika_schema`	The embedded JSON Schema for `*.nika` — the structural contract an agent authors against.
`nika_examples`	Browse the embedded runnable examples; with a `slug`, that example’s full source.
`nika_template`	The canonical workflow skeletons (chain · gate-and-act · fanout · …); with a `name`, that skeleton’s source — copy it, never invent structure.
`nika_canon`	The spec canon SSOT (`canon.yaml`) — the locked counts and names. Cite it, never a remembered number.
`nika_catalog`	The embedded provider/model catalog — models, capabilities, context windows, API-key env vars.
`nika_tools`	The embedded builtin-tool catalog — every `nika:*` tool with its model-facing JSON Schema.
`nika_inspect`	The typed graph of a checked workflow (`graph_format: 3` · an unwind task is a `finally` node, its edge carries `predicate: unwind`) — nodes, edges with their kinds, byte-parity with `nika inspect --format json` and the LSP. Regenerate a pinned golden from the binary, never hand-edit it.

The split is deliberate: validate (nika_check · nika_explain) and learn (nika_schema · nika_examples · nika_template · nika_canon · nika_catalog · nika_tools · nika_inspect).

Why read-only is the whole point

A .nika can declare exec: shell steps — that is the language working as designed. An MCP tool that ran workflows would hand every wired agent a shell with your credentials, one prompt-injection away. So the oracle refuses the category:

No nika_run, no nika_generate, no write tools — ever. Authoring is the skill’s job (the agent writes the file, you review it); running is the CLI’s job (nika run, with budget flags, under your eyes).
Secrets never transit the oracle. The catalog names the env var a provider needs; it never reads or returns values.
What the trace’s hash chain proves — and what it does not — is stated plainly in machine surfaces: tamper-evidence for the recorded run, not a signature. Author-binding signatures exist (nika sign); they do not replace nika trace verify.

Context budget

The oracle is lean by design — a handful of read-only tools with compact outputs, sized so wiring it costs an agent almost nothing. Clients that support per-server tool filtering can narrow further (e.g. expose only nika_check + nika_template to a coding agent).

Verify a wiring

Ask the connected agent to list its tools — the nine names above should appear. From a shell, the JSON-RPC handshake works too:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | nika mcp

And the last inch — a real nika_check call. workflow takes the file’s source text (the oracle has no filesystem access by design), so shell in the file’s contents:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  "{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"nika_check\",\"arguments\":{\"workflow\":$(python3 -c 'import json,sys;print(json.dumps(open(sys.argv[1]).read()))' flow.nika)}}}" \
  | nika mcp

A clean workflow answers with the audit verdict in content[0].text — same output as nika check, over the wire.

YAML

Language fields

CLI & errors

Data catalogs

Workspace

Documentation system

Tool contracts

Nika as an MCP server

Start it

The 9 tools

Why read-only is the whole point

Context budget

Verify a wiring

​Start it

​The 9 tools

​Why read-only is the whole point

​Context budget

​Verify a wiring

Start it

The 9 tools

Why read-only is the whole point

Context budget

Verify a wiring