Skip to main content

Using the CLI as an MCP server

The np binary can run as a Model Context Protocol server. Once it's connected, your AI coding agent can list, read, and describe nullplatform entities directly, instead of guessing at API calls or asking you to run commands and paste the output back.

There's no infrastructure to deploy and no second set of credentials. The server runs locally as a subprocess of your AI client, and it authenticates with the same session np already uses.

info

np mcp is available from np 2.9.0. Run np upgrade to update, then check with np --version.

What your agent can do​

The server exposes nullplatform as a small set of tools rather than one tool per API operation, so your agent's context stays usable.

ToolWhat it does
np_listList entities, with filters and pagination
np_readRead a single entity
np_describeReport an operation's parameters and request body fields
np_lake_queryRun read-only SQL against the Customer Lake
np_auth_statusReport whether the session works, and for which profile
np_skills, np_skill_readBrowse and read nullplatform's AI skills
np_create, np_update, np_patch, np_deleteCreate and modify entities. Only with --allow-writes

Your agent works within your permissions. The server can't do anything your user can't do from the terminal.

Install it in your AI client​

Run np mcp install. It detects which AI clients you have and configures each one:

np mcp install
Installing MCP server "nullplatform"
  binary   /Users/you/.local/bin/np
  profile  default (written as NP_PROFILE in each client's env)
  mode     read-only

  ✓ Claude Code  Claude Code user config (managed by `claude mcp`)
  ✓ Cursor       /Users/you/.cursor/mcp.json

Restart your AI client afterwards so it picks up the new server.

Three clients are detected automatically: Claude Code, Cursor, and Codex. Use --client to configure just one:

np mcp install --client cursor

The installer writes the absolute path of your np binary. That matters more than it sounds: applications launched from Finder or the dock don't inherit your shell's PATH, so a configuration that just says np works in a terminal-based client and fails in a graphical one with nothing but a connection error.

Re-running np mcp install updates the entry instead of duplicating it, so it's also how you repair one that points at an old binary.

Any other MCP client​

For clients without a dedicated adapter, --print-config writes the standard MCP snippet to standard output with the path and profile already resolved:

np mcp install --print-config
{
  "mcpServers": {
    "nullplatform": {
      "type": "stdio",
      "command": "/Users/you/.local/bin/np",
      "args": ["mcp", "serve"],
      "env": {
        "NP_PROFILE": "default"
      }
    }
  }
}

Paste that into your client's MCP configuration.

Profiles​

The np CLI supports multiple profiles, each with its own stored session. The MCP server uses them the same way, with one difference that's easy to miss.

Graphical applications don't inherit your shell environment, so an export NP_PROFILE=prod in your shell profile is invisible to a server your editor launches. To avoid that, the installer writes NP_PROFILE directly into the client's configuration, and tells you which profile it anchored.

To install against a specific profile, pass --profile:

np login --profile prod
np mcp install --profile prod

The entry is named nullplatform-prod rather than nullplatform, so profiles don't collide. You can create as many profiles as you need. There's no limit and no registration step: np login --profile <name> creates one.

One profile per client​

Because each client has its own configuration, you can point each at a different profile. Run the installer once per client:

np mcp install --client claude-code --profile prod
np mcp install --client cursor      --profile staging
note

Without --client, the installer acts on every detected client using the same profile. Pass --client when you want them to differ.

Several profiles in one client​

You can also register more than one server in the same client, which is often more useful. MCP clients namespace tools per server, so your agent sees both and picks:

np mcp install --profile prod
np mcp install --profile staging --allow-writes

That gives you an environment policy your agent can act on: read-only against production, writes allowed against staging.

tip

If a profile has no usable session yet, np mcp install still writes the entry and tells you to run np login --profile <name>. You can set everything up before logging in.

Read-only by default​

The server starts read-only. The tools that create, update, patch, and delete entities are not registered at all, so there's nothing for an agent to call by mistake. The boundary is the absence of the tools, not a check that could be talked around.

To enable them, install with --allow-writes:

np mcp install --allow-writes

The mode is per installation, which is why two entries on different profiles work well: your agent can read production and write to staging in the same session, without either being a decision it makes on its own.

warning

With --allow-writes, your agent can create, modify, and delete real nullplatform entities. Enable it deliberately, and prefer scoping it to a non-production profile.

Checking and removing​

np mcp status reports what each client is actually configured with, reading it back from the client rather than assuming the last install still holds:

np mcp status
MCP server "nullplatform" — profile default

  ✓ Claude Code  installed
      Command: /Users/you/.local/bin/np
      Args: mcp serve
      Environment:
        NP_PROFILE=default

  · Cursor       not detected — /Users/you/.cursor does not exist

To remove an entry:

np mcp uninstall
np mcp uninstall --client cursor
np mcp uninstall --name nullplatform-staging

np mcp install and np mcp uninstall both accept --dry-run, which prints what would change and writes nothing.

Headless and CI​

For non-interactive environments, set NULLPLATFORM_API_KEY in the process environment that launches the server. Nullplatform never writes credentials into a client configuration, only the profile name.

That's deliberate. Project-scoped MCP configurations such as .mcp.json and .cursor/mcp.json are commonly committed to git, and an installer that wrote an API key into one would publish your credential into your repository.

NULLPLATFORM_API_KEY=AAAA.1234567890abcdef1234567890abcdefPTs= np mcp serve