# MCP

> Let Claude Code, Cursor, Codex and other agents use Nodus through one MCP server, with confirmation before anything is created.

Source: https://nodus-platform-site.pages.dev/docs/guides/mcp/
Build revision: 211ad9f836655b1c3a2668c4693e442471f28614

Nodus runs one [MCP](https://modelcontextprotocol.io) server. An agent that speaks MCP can list your Jobs, read their logs, estimate what a manifest would cost, and, after you confirm, create it. The tools work on every kind of resource with the same names, so a new kind needs no new tools.

The agent acts as you, with a role and scopes that you choose when you connect it. It can never do more than your own role allows.

## Connect a client

There are two ways to connect. The **hosted** server runs at `https://api.nodus-compute.ai/mcp` and signs you in with your browser. The **local** server is `nodus mcp`, which the client starts on your machine and which acts with your `nodus login`.

Note

`nodus mcp install CLIENT` writes the setup for you. It adds only a `nodus` entry to the client’s own configuration file, keeps a copy of the original next to it, and refuses to replace a different `nodus` entry unless you pass `--force`. Add `--dry-run` to see what would change.

### Claude Code

Terminal window

```console
$ claude mcp add --transport http nodus https://api.nodus-compute.ai/mcp
```

Run `/mcp` in Claude Code and choose **nodus** to sign in. Or for the local server:

Terminal window

```console
$ nodus login
$ nodus mcp install claude
```

### Cursor

Use the Cursor link on the [connect page](https://nodus-platform-site.pages.dev/connect/), or:

Terminal window

```console
$ nodus mcp install cursor --hosted
```

Drop `--hosted` to run `nodus mcp` locally instead. Cursor reads `~/.cursor/mcp.json`.

### Codex

Terminal window

```console
$ nodus mcp install codex --hosted
$ codex mcp login nodus
```

Codex reads `config.toml` in `$CODEX_HOME` (`~/.codex` by default). Without `--hosted`, the entry starts `nodus mcp`.

### Other clients

Any client that supports streamable HTTP can use the hosted URL. For one that starts a command, use [`/mcp.json`](https://nodus-platform-site.pages.dev/mcp.json) (the local server) or [`/mcp-hosted.json`](https://nodus-platform-site.pages.dev/mcp-hosted.json) (the hosted one).

## What the agent can do

When you sign in to the hosted server, a consent page asks which org and which scopes the client may use. The tools it lists follow those scopes, so a client granted only `jobs:read` sees only the tools that read Jobs.

|Tool|What it does|
|-|-|
|`whoami`, `api_resources`, `explain`|Who you are, the kinds and their fields. Agents start here.|
|`get`, `describe`, `events`|Read objects, a summary with its recent events, and Events.|
|`logs`, `wait`, `outputs`|Read logs (at most 2,000 lines), wait up to 60 seconds for a state, list outputs or get a download link valid for 10 minutes.|
|`estimate`|Dry-run a manifest: the cost estimate, anything blocking it, and the `etag` that `apply` needs.|
|`apply`|Create an object from a manifest. See below.|
|`delete`, `set_state`, `request`, `record`|Delete an object, suspend or resume it, ask for an action such as a restart, and create a record such as a webhook replay.|
|`exec`, `files`|Run a command in a running Sandbox, Workspace or Job (up to 300 seconds), and read, write or list its files.|

A local server also has three tools that touch your machine’s files: `upload_source` (upload a directory as a code blob; it follows `.gitignore` and `.nodusignore`), `download_output` (save an output, verified against its checksum) and `cp` (copy a file to or from a Sandbox, Workspace or Job).

## Nothing is created without a confirmation

`apply` does not create anything the first time. It returns the dry-run: the object as it would be stored, its estimated cost, and an `etag`. The agent shows you that. Only when you accept does it call `apply` again with `confirmed: true` and the same `etag`, and the create fails if the estimate changed in between. Objects created this way carry the label `nodus.dev/launched-by` with the value `mcp`.

MCP never completes a payment. Applying a `TopUp` returns a checkout link for you to open yourself.

## Logs and output are data, not instructions

Logs, command output and file contents come back marked as untrusted. They can contain anything a program wrote, so an agent must treat them as data. Nodus also stops a tool call that touches more than your grant allows, even if text in a log asks for it.

## Change or remove access

Console › Settings › Connected agents lists each client with its scopes. Narrowing or deleting a grant takes effect within 30 seconds, even for a client that already holds a token. See [Connected agents](https://nodus-platform-site.pages.dev/docs/guides/access/connected-agents/).

Terminal window

```console
$ nodus get oauthgrants
$ nodus delete oauthgrant claude-code-3fa2c1
```

## Troubleshooting

|Symptom|What to do|
|-|-|
|The client lists fewer tools than you expect|The grant lacks the scope. Reconnect and approve more scopes, or check your role with `nodus auth can-i`.|
|`not logged in` from `nodus mcp`|Run `nodus login`, or set `NODUS_API_KEY`.|
|`install` says there is a different `nodus` connection|Remove that entry, or pass `--force` to replace it.|
|`install` says it cannot parse the file|Fix the file’s syntax first. Nothing was changed.|
|A write was refused with a changed estimate|Ask the agent to run `estimate` again and show you the new numbers.|