MCP Introduction

Plug your AI coding agent directly into Nodion. No local daemon, no custom glue code.

Nodion runs a Remote MCP server at https://mcp.nodion.com/mcp. Any MCP-compatible client (Claude Code, Cursor, Zed, OpenAI Codex, Gemini CLI, Windsurf) can authenticate with a Bearer token and drive your Nodion projects in natural language.

How it works

MCP is an open protocol that lets LLMs call external tools. The Nodion MCP server exposes the actions an AI agent needs to manage applications and run code in isolated containers: listing projects, deploying new versions, reading env vars, fetching deployment logs, plus a full runner surface including the runs.exec sandbox primitive. Each tool maps 1:1 to a public REST API endpoint.

Your API key scopes decide what the agent can do. A read-only key exposes only read tools; a deploy-capable key unlocks deploy, env.set and the other write tools.

1. Create an API key

Head to my.nodion.com → User Settings → Security, click Add API Key, choose the scopes you want to grant and optionally restrict the key to specific projects or set an expiry. The token is shown only once, so copy it straight into your AI client's config.

See the Authentication API docs for the full scope matrix.

2. Connect your AI client

Claude Code

bashclaude mcp add --transport http nodion https://mcp.nodion.com/mcp \
  --header "Authorization: Bearer YOUR_NODION_API_KEY"

Start or restart a Claude Code session. The Nodion tools become available in chat immediately.

Zed

Open the command palette, run zed: open settings and add:

json{
  "context_servers": {
    "nodion": {
      "url": "https://mcp.nodion.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NODION_API_KEY"
      }
    }
  }
}

OpenAI Codex

Edit ~/.codex/config.toml:

toml[mcp_servers.nodion]
url = "https://mcp.nodion.com/mcp"

[mcp_servers.nodion.http_headers]
Authorization = "Bearer YOUR_NODION_API_KEY"

For cleaner key handling, store the token in an env var and use env_http_headers instead.

Gemini CLI

Edit ~/.gemini/settings.json:

json{
  "mcpServers": {
    "nodion": {
      "httpUrl": "https://mcp.nodion.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NODION_API_KEY"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

json{
  "mcpServers": {
    "nodion": {
      "url": "https://mcp.nodion.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_NODION_API_KEY"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json with the same JSON shape as Cursor.

3. Verify the connection

The easiest sanity check is the MCP Inspector:

bashnpx @modelcontextprotocol/inspector https://mcp.nodion.com/mcp

Set the Authorization header to Bearer YOUR_NODION_API_KEY and you will see the tool manifest.

Available tools

Write tools require confirm=true, so the model must ask before making changes:

Read — foundational

whoami. Returns the authenticated Nodion user.
projects.list. Lists projects this key can access.
projects.use. Selects the active project for the session.
regions.list. Lists available Nodion regions. Returns ids needed by apps.create / runners.create.
instance_types.list. Lists CPU/memory/price for every instance type. Returns ids needed by apps.create / runners.create.

Read — applications

apps.list, apps.get. Browse applications in the current project.
apps.logs. Last N runtime stdout/stderr lines from the running instances of an application.
deployments.list, deployments.get. Inspect past deployments.
deployments.logs. Build and release pipeline log lines of a specific deployment (image pull, build, release output). Different from apps.logs, which is the container's runtime output.
env.list. Lists environment variables.
domains.list. Lists domains attached to an application.
processes.list. Lists processes (web, worker, cron, etc.) with current instance_amount.

Read — git integrations

integrations.list. Lists git integrations available to the current project owner (GitHub, GitLab, Bitbucket, Nodion Git).
repos.list. Lists repositories accessible through a given integration.
branches.list. Lists branches of a given repository.

Read — runners and runs

runners.list, runners.get. Browse runners and their warmup state.
runs.list, runs.get. Inspect past runs and their status.
runs.logs. Paginated log lines of a run, with optional after_id cursor.
runs.tail. Last N log lines as a single text blob, LLM-friendly.

Write — applications

deploy. Creates a new deployment.
env.set. Creates or updates an environment variable.
env.unset. Removes an environment variable.
processes.scale. Sets a process's instance_amount. Pass 0 to stop the process.

Write — runners and runs

runners.create, runners.update, runners.delete. Manage runner configuration.
runners.warmup. Pre-pull a runner's image. Idempotent, low-risk; no confirm required.
runs.create. Trigger an asynchronous run. Returns immediately with a pending run id.
runs.stop. Cancel a pending or running run.

Sandbox execution

One convenience tool combines triggering, polling and log collection into a single synchronous call. It is the building block for AI-agent code execution:

runs.exec. Run a command and wait for the result. Two modes:
- Pass runner_id to use an existing runner.
- Pass image_name + image_tag + region_id + instance_type_id to spin up an ephemeral runner that is deleted automatically once the run finishes (or times out).
Returns { run_id, runner_id, ephemeral, status, exit_code, duration_ms, output, truncated, timed_out }. Default timeout 60 seconds, max 300. Output is capped at 30 KB. For long-running jobs use runs.create + polling instead.

Audit log

Every MCP tool call is audited. The originating API key, tool name, project, arguments and duration are recorded so you can review what an agent did on your behalf. View it under User Settings → Security → Audit.

Next steps

Prefer a command-line experience? The CLI exposes the same capabilities without needing an MCP client.
Building a custom agent? Talk to the REST API directly. MCP tools are a thin wrapper on top.
New tools and fixes ship on the Changelog.