CLI MCP Server Concept

The Niksphere CLI ships a built-in Model Context Protocol (MCP) server, allowing AI coding agents such as Claude Code, Cursor, Antigravity, or VS Code Copilot to operate the CLI directly and to receive Niksphere-specific architectural guidance while generating or editing app code.

This document explains how that server is constructed and how it is registered with AI clients. It is aimed at developers extending the CLI or evaluating how AI tooling integrates with the platform — for day-to-day usage, see the CLI Command Reference.

nik mcp is a local MCP server: it communicates over stdio as a subprocess spawned directly by the AI client, and is only intended for local IDEs and CLIs (Claude Code, Cursor, Antigravity, VS Code Copilot) running on the same machine as the project. It has no network listener and cannot be exposed as a hosted endpoint, so it is not compatible with remote or cloud-hosted AI software that expects an HTTP- or SSE-reachable MCP server (e.g. web-based "custom connectors" such as claude.ai or ChatGPT).

1. Two-Command Design

MCP support in the CLI is deliberately split into two independent commands with different callers and different lifecycles:

Command	Purpose	Typical Caller
nik mcp	Starts the actual MCP server on stdio.	An MCP-compatible AI client, launched as a subprocess. Not intended to be run manually.
nik dev mcp enable|disable|show	Registers or removes nik mcp in a project's AI client configuration files.	A developer (directly, or via the VS Code Extension), once per project.

Separating the two keeps nik mcp a single-purpose protocol endpoint, while nik dev mcp lives alongside the CLI's other project-local development commands (nik dev compile, nik dev init, nik dev lsp).

Rendering diagram...

2. The MCP Server (nik mcp)

2.1 Dynamic Command-to-Tool Mapping

Rather than hand-maintaining a separate tool catalog, nik mcp walks the CLI's own command tree at startup and registers every leaf command as an MCP tool:

• The tool name is derived from the command path (e.g. nik env app install becomes the tool env_app_install).
• The command's Short/Long description becomes the tool description.
• Positional arguments (parsed from the command's Use string) and flags become typed tool parameters, preserving required annotations.
• Help, shell-completion, and the mcp command itself are excluded from registration.

This means every capability exposed through the CLI is automatically available to AI agents as soon as it ships as a new command — there is no separate tool definition to keep in sync.

2.2 Tool Execution Model

A tool call does not execute in-process. Each invocation re-executes the CLI binary as a fresh subprocess with the mapped arguments and a forced --json flag, capturing stdout/stderr and returning them to the AI client:

Rendering diagram...

This keeps every MCP tool call bound by the exact same permission boundary, authentication state, and output contract as running the equivalent command by hand in a terminal — there is no privileged in-process code path an agent can reach that a human operator couldn't also invoke directly.

2.3 Static Architectural Guidance

Beyond executable tools, nik mcp also publishes a fixed set of server instructions (via the MCP instructions field), read by the AI client once at connection time. These encode Niksphere-specific YAML modeling conventions that aren't otherwise discoverable from the command surface, e.g.:

• Never quoting caption/description string values.
• Extracting recurring field groups into a reusable FieldSet instead of duplicating them.
• Preferring a dedicated Enum over a free-text String for fixed value lists.
• One Niksphere object per file, named after its kind (e.g. CustomerEntity.yaml).
• Always generating uid values via the generate_uid tool rather than inventing them.

Because these instructions ship with the CLI binary itself, every AI agent connected to a given Niksphere CLI version enforces the same modeling conventions, independent of which client or model is being used.

3. Client Registration (nik dev mcp)

nik mcp on its own does not make an AI client aware that it exists — each client discovers local MCP servers through its own project-scoped configuration file. nik dev mcp enable writes the small set of files needed to register nik mcp with every client the CLI currently knows how to configure:

Client ID	Configuration File	Root Key
claude-code	.mcp.json	mcpServers
cursor	.cursor/mcp.json	mcpServers
antigravity	.agents/mcp_config.json	mcpServers
vscode	.vscode/mcp.json	servers

All four entries point at the same launch command: {"command": "nik", "args": ["mcp"]}.

nik dev mcp enable [path]              # registers all known clients
nik dev mcp enable [path] --client vscode,cursor   # limit to specific clients
nik dev mcp disable [path]             # removes the Niksphere entry again
nik dev mcp show                       # prints copy-pasteable snippets for clients not in the registry

3.1 Merge, Not Overwrite

Because a project may already use other MCP servers (e.g. a Playwright or GitHub server), nik dev mcp enable/disable only ever read, modify, and write back a single niksphere entry inside each file's root object — every other entry, and any other top-level key in the file, is left untouched. Running enable again after nothing changed is a no-op (reported as unchanged) rather than rewriting the file, which keeps unrelated git diff noise out of the project. disable mirrors this: it removes only the niksphere entry, and deletes a configuration file entirely only once it would otherwise be left empty.

3.2 Project-Scoped by Design

Registration is intentionally limited to project-scoped configuration files that live inside the app's own directory (and can be committed to version control so a whole team gets the same setup). Global or user-level client configuration — such as Claude Desktop's claude_desktop_config.json — is out of scope: it is a different mechanism entirely (not project-scoped, and shared across every project on a machine), and clobbering it automatically would risk affecting configuration unrelated to the current Niksphere project.

4. Related Documentation

• CLI Command Reference — Full command and flag reference, including nik mcp and nik dev mcp.
• Engine Authentication & Identity Concept — How CLI commands invoked by MCP tools authenticate against the Engine.
• Layer System ("Everything is an App") — Background on the YAML modeling concepts referenced in the server's architectural guidance.