---
title: Connect an AI assistant to nullplatform
sidebar_label: MCP server
toc_max_heading_level: 3
doc_id: 2ae08174-3630-426c-906f-fb1a5f85d9e8
description: >-
  Connect Claude, Kiro, Cursor, Codex, or any AI assistant that supports MCP to
  your nullplatform organization with one URL. You sign in, approve what the
  agent can do, and manage that access from your user settings.
keywords:
  - MCP
  - Model Context Protocol
  - MCP server
  - AI assistant
  - AI agents
  - Claude
  - Kiro
  - Cursor
  - Codex
  - personal access tokens
  - nullplatform
canonical: 'https://docs.nullplatform.com/docs/mcp-server'
---
# Connect an AI assistant to nullplatform

The nullplatform MCP server is how an AI assistant gets access to your organization. Once it's connected, the agent can query, troubleshoot, and operate nullplatform for you, **as you**: with only the access you approve, and never more than you have. You add one URL, sign in, and choose what the agent can do. There's nothing to install and no API key to copy.

It works with any assistant that supports remote [MCP](https://modelcontextprotocol.io) servers: Claude Code, Claude on the web and desktop, Cowork, Kiro, Cursor, Codex, and others. That includes people who never open a terminal: they can ask about their deployments from a chat window.

The [AI plugins](/docs/ai-ops/ai-plugins) teach your assistant how nullplatform works. The MCP server gives it access to your organization. They work well together, and each works on its own.

## How it works

1. You add your organization's MCP URL to your AI assistant.
2. The first time the agent connects, your browser opens. You sign in to nullplatform and approve the connection, choosing what the agent can do.
3. Nullplatform creates a [personal access token](/docs/authorization/personal-access-tokens) for that connection. The agent acts **as you**, and it can never do more than you.

The connection lasts until that token expires or you delete it from your user settings. In between, it renews its session on its own, so you don't sign in again every hour.

## Your server URL

It's the URL you use to sign in to nullplatform, with `/mcp` at the end:

```
https://<your-org>.app.nullplatform.io/mcp
```

For example, if you sign in at `https://acme.app.nullplatform.io`, your MCP server is `https://acme.app.nullplatform.io/mcp`.

## Connect your AI assistant

### Claude Code

Add the server:

```bash
claude mcp add --transport http nullplatform https://<your-org>.app.nullplatform.io/mcp
```

Then start a session, run `/mcp`, select **nullplatform**, and choose **Authenticate**. Your browser opens so you can [sign in and approve access](#sign-in-and-approve-access). Back in Claude Code, you'll see `Authentication successful. Connected to nullplatform.`

> 💡 **Tip:** `claude mcp add` registers the server for the current project. Add `--scope user` to make it available in every project.

### Claude on the web, desktop, and Cowork

Add nullplatform as a custom connector: open **Settings > Connectors**, click **Add custom connector**, and paste your server URL. Claude opens the sign-in page the first time you connect.

### Other assistants

Kiro, Cursor, Codex, VS Code, and other assistants that support remote MCP servers take the same URL. Add it as a remote (HTTP) MCP server in the assistant's settings. The assistant opens your browser to sign in the first time it connects.

## Sign in and approve access

After you sign in, nullplatform asks you to approve the connection. Walk through the screen below:

<GuidedTour
  alt="The Connect an agent to nullplatform screen, recreated as an HTML scene with a step-by-step walkthrough"
  steps={[
    {
      title: '1. Check who is asking',
      body: 'The screen names the agent and your organization. Continue only if you started the connection from your assistant yourself.',
      anchor: 'consent-request',
      placement: 'bottom',
    },
    {
      title: '2. Name it and set how long it lasts',
      body: 'Both come filled in. The name helps you tell connections apart, and a connection lasts a year at most.',
      anchor: 'consent-identification',
      placement: 'bottom',
    },
    {
      title: '3. Choose what the agent can do',
      body: 'Same access as me follows your roles as they change. Choose grants limits the agent to the resources, roles, or permissions you pick.',
      anchor: 'consent-access',
      placement: 'top',
      align: 'end',
    },
    {
      title: '4. Authorize',
      body: 'Your browser sends you back to your assistant, connected. The connection shows up as a personal access token in your user settings.',
      anchor: 'consent-authorize',
      placement: 'top',
    },
  ]}
>
  <ConsentScene />
</GuidedTour>

:::tip Keep an agent read-only
Choose **Choose grants**, pick a resource, and give it only the **Member** role. The agent can read everything at that resource and change nothing.
:::

## What your agent can do

The server exposes nullplatform as a small set of tools instead of one tool per API operation, so the agent's context stays usable:

| Tool | What it does |
|---|---|
| `np_list` | List entities of one type, with filters |
| `np_read` | Read one entity by ID |
| `np_describe` | Describe an API operation: its parameters and request body |
| `np_lake_query` | Run read-only SQL against the [data lake](/docs/data-lake/), for counts, aggregates, and questions that cross entities |
| `np_logs` | Fetch the application logs of a scope |
| `np_metrics` | Fetch a scope's metrics: requests per minute, response time, error rate, CPU, and memory |
| `np_docs_search` | Search the nullplatform documentation |
| `np_skills`, `np_skill_read` | Browse and read nullplatform's AI skills, the same catalog as the [AI plugins](/docs/ai-ops/ai-plugins) |
| `np_auth_status` | Report whether the connection works, and for which organization |
| `np_create`, `np_update`, `np_patch`, `np_delete` | Create, change, and delete entities |

:::info
The agent can change something only if the access you approved allows it, and anything outside it is refused. The server also tells the agent to confirm with you before it creates, changes, or deletes anything.
:::

## Manage and revoke access

Every connection is a personal access token under **User settings > Personal access tokens**, tagged `source | mcp`. Search for `mcp` to list them all. From there you can see what each one can do, extend it, or delete it.

<UserSettingsScene filter="mcp" />

Deleting the token cuts the agent's access right away. To use the server again, connect and approve a new token.

:::note
Removing the server from your assistant doesn't delete its token. Delete it from your user settings too, or it stays listed until it expires.
:::

## Use an API key instead

Agents that can't open a browser, like one running in CI, can authenticate with an [API key](/docs/authorization/api-keys) sent in the `X-API-Key` header. A [personal access token](/docs/authorization/personal-access-tokens) works too, if the agent should act as you:

```bash
claude mcp add --transport http nullplatform https://<your-org>.app.nullplatform.io/mcp \
  --header "X-API-Key: AAAA.1234567890abcdef1234567890abcdefPTs="
```

The key's grants decide what the agent can do.

:::warning Keep keys out of shared configuration
Project-scoped MCP configuration files, such as `.mcp.json`, are often committed to git. Don't put a key in one: read it from an environment variable or keep the entry in your user configuration.
:::

## The hosted server or the CLI

The [CLI](/docs/cli/mcp) can also run as an MCP server, locally, with the session `np` already has. Use the hosted server when you want sign-in from the browser, an access you choose per connection, and support for assistants that don't run on your machine. Use the CLI when you already work with `np` profiles and want the server to start read-only.

## Next steps

- [Personal access tokens](/docs/authorization/personal-access-tokens): see, extend, and delete the tokens your connections use
- [Set up the AI plugins](/docs/ai-ops/ai-plugins): teach your coding assistant how nullplatform works
- [Using the CLI as an MCP server](/docs/cli/mcp): run the server locally with your `np` session
- [Roles](/docs/authorization/roles): what each role lets the agent do