MCP

Nodus runs one MCP 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

$ 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:

$ nodus login
$ nodus mcp install claude

Cursor

Use the Cursor link on the connect page, or:

$ nodus mcp install cursor --hosted

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

Codex

$ 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 (the local server) or /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.

$ 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.