---
sidebar_label: MCP server
toc_max_heading_level: 3
doc_id: a052d70a-12b6-4910-8c1e-52671db801e5
description: >-
  Run the np CLI as a Model Context Protocol server so AI coding agents can
  query and operate nullplatform through your existing session.
keywords:
  - MCP
  - Model Context Protocol
  - CLI
  - Claude Code
  - Cursor
  - Codex
  - AI agents
  - nullplatform
---

# Using the CLI as an MCP server

The `np` binary can run as a [Model Context Protocol](https://modelcontextprotocol.io) 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](/changelog/cli-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.

| Tool | What it does |
|---|---|
| `np_list` | List entities, with filters and pagination |
| `np_read` | Read a single entity |
| `np_describe` | Report an operation's parameters and request body fields |
| `np_lake_query` | Run read-only SQL against the Customer Lake |
| `np_auth_status` | Report whether the session works, and for which profile |
| `np_skills`, `np_skill_read` | Browse and read nullplatform's [AI skills](/docs/tutorials/ai-plugins-setup) |
| `np_create`, `np_update`, `np_patch`, `np_delete` | Create 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:

```bash
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:

```bash
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:

```bash
np mcp install --print-config
```

```json
{
  "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](/docs/cli/#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`:

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

```bash
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:

```bash
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.

```bash
NULLPLATFORM_API_KEY=AAAA.1234567890abcdef1234567890abcdefPTs= np mcp serve
```

## Related

- [CLI](/docs/cli/): installing `np`, authentication, and profiles
- [Get started with nullplatform AI plugins](/docs/tutorials/ai-plugins-setup): the skills catalog your agent can also use