---
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.
3. The connection uses a [personal access token](/docs/authorization/personal-access-tokens). If you have tokens from earlier connections, you can continue with one and keep the access it has. Otherwise you create a new one and choose what the agent can do. Either way, 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

If you've connected an agent before, the screen first asks you to **choose a connection**. It lists the tokens your earlier connections created, most recently used first. Pick one and click **Continue** to reuse it with its current access: no new token is created. To set up different access, click **Create a new connection** and fill in the form below.

To create a new 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 access of every agent that uses it, right away. To use the server again, connect and pick another token or create a new one.

:::note
Disconnecting the agent, or removing the server from your assistant, doesn't delete its token. The token keeps working until it expires, and you can pick it again the next time you connect. To cut its access for good, delete it from your user settings.
:::

## 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