Developing with AI Coding Agents

This guide explains how to connect an AI coding agent (Claude Code, Cursor, Antigravity, or VS Code Copilot) to your Niksphere project, so it can run CLI commands directly and follow Niksphere-specific modeling conventions automatically. For the underlying design, see the CLI MCP Server Concept.

Prerequisites

1. Niksphere CLI (nik) installed (see Niksphere CLI Installation & Setup Guide).
2. Niksphere VS Code Extension installed, if you want to register from within VS Code rather than the terminal.
3. An MCP-compatible AI client — Claude Code, Cursor, Antigravity, or VS Code Copilot.

1. Registering the Niksphere MCP Server

Registering writes small configuration files into your project (e.g. .mcp.json) that tell your AI client how to launch nik mcp. You only need to do this once per project.

From VS Code

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P) and run Niksphere: Enable AI Agent Integration (MCP).
2. A multi-select list appears, showing every AI client the installed CLI knows how to configure, all pre-checked. Uncheck any you don't use, then confirm.
3. A notification confirms which files were written (e.g. Successfully registered Niksphere MCP server for project at ...).

From the terminal

nik dev mcp enable

This registers every supported client for the current directory. To register only specific clients:

nik dev mcp enable --client claude-code,cursor

TIP

Running enable again after nothing changed is a no-op — it won't touch files or produce unnecessary git diff noise. It's safe to run any time you're unsure whether registration is up to date.

2. Verifying the Connection

Restart or reload your AI client after registering (most clients only read their MCP configuration file at startup). Once connected, the client should list a niksphere MCP server offering:

• One tool per CLI command (e.g. env_app_install, dev_generate_uid) — the agent can run nik commands directly instead of asking you to run them.
• A set of architectural instructions covering Niksphere YAML conventions (FieldSets, Enums, UID generation, file naming) that the agent follows automatically when generating or editing app code.

If the client doesn't show the server, check the "Niksphere CLI" output channel in VS Code (View → Output, select "Niksphere CLI" from the dropdown) for the underlying command that was run, or re-run nik dev mcp enable from the terminal to see any error directly.

3. Working with a Connected Agent

Once connected, you can ask the agent to do things like:

• "Add a Status field to the Order entity as an Enum with values Draft, Confirmed, Shipped." — the agent generates the Enum and Entity YAML, using generate_uid for every new ID instead of inventing one.
• "Compile this app and fix any validation errors." — the agent runs nik dev compile as a tool and iterates on the result.
• "Extract the shared Address fields used in Customer and Supplier into a FieldSet." — the agent follows the modeling conventions from the server's instructions without being told about them explicitly.

4. Removing or Changing the Registration

From VS Code

Run Niksphere: Disable AI Agent Integration (MCP) from the Command Palette and select which clients to remove — this only removes the Niksphere entry, leaving any other MCP servers already configured in those files untouched.

From the terminal

nik dev mcp disable

Clients not in the list

nik dev mcp enable/disable only cover clients with a known project-scoped configuration format. For any other MCP-compatible tool, print a ready-to-paste configuration snippet instead:

nik dev mcp show

5. Troubleshooting

AI client shows no tools, or an outdated set of tools

The client only reads its MCP configuration at startup — restart it after running enable for the first time, or after upgrading the Niksphere CLI (new CLI versions can add new tools).

VS Code reports "Niksphere CLI (nik) could not be found"

See the CLI Not Found troubleshooting section in the VS Code development guide.

The client picker in VS Code shows an error instead of a list

The extension asks the installed CLI which clients it supports (nik dev mcp show --json) rather than hardcoding the list. This error means the resolved nik executable is missing, too old to have this command, or failed to run — verify nik dev mcp show works from a terminal first.

Related Documentation

• CLI MCP Server Concept — How the MCP server and client registration work internally.
• CLI Command Reference — Full reference for nik mcp and nik dev mcp.
• Developing & Publishing Apps in VS Code — The rest of the VS Code development workflow (compile, publish, LSP).